deimos

GitHub About: Deimos is an MIT-licensed terminal coding agent: one deimos command, pluggable model backends (Anthropic Claude, OpenAI-compatible APIs, Gemini, GitHub Models, Ollama, Atomic Chat, and others), tools, MCP, and slash commands. This repo ships the CLI plus a VS Code extension and a dark terminal theme.

Legal: not affiliated with Anthropic, PBC, or any other vendor. Trademarks, MIT terms, and how to raise concerns: LEGAL.md (general information only—not legal advice).

Upstream: this repo is an independent distribution (@dxa-dev/deimos on npm). Core CLI behaviour is periodically aligned with dxiv/dxa-deimos (see docs/maintainers.md for how to sync src/). Docs, legal framing, CI, and packaging here are specific to this fork.

Status: Active — full CLI, documentation, VS Code extension, and CI; this is not a placeholder stub.

What's here: bin/, dist/cli.mjs, src/, vscode-extension/, docs/, optional python/, .github/ workflows, and root policy files—see Repository structure for paths.

Quick start · Setup · Providers · Source build · Repo layout · VS Code · Contributing · Security · Community

New to terminals or npm? docs/non-technical-setup.md → Windows or macOS / Linux → checklist → first run.
All docs: docs/README.md.

Why use it

• One CLI for cloud APIs and local inference
• /provider for guided setup and a saved profile
• Bash, file tools, grep/glob, agents, tasks, MCP, web helpers
• Optional VS Code integration from this repo

Quick start

You need Node.js 20+ and a terminal. If that’s new territory, use docs/non-technical-setup.md first.

Install

npm: @dxa-dev/deimos

GitHub Packages: dxa-dev / deimos.

Use npm to install the published CLI. GitHub is for source code, issues, and discussions—not a separate “installer” download.

npm install -g @dxa-dev/deimos

Install ripgrep and ensure rg is on your PATH. If the CLI prints ripgrep not found, fix PATH, then open a new terminal window — Troubleshooting has more detail.

Start

deimos

Inside Deimos:

• run /provider for guided provider setup and saved profiles
• run /onboard-github for GitHub Models onboarding

Fastest OpenAI setup

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-your-key-here
export OPENAI_MODEL=gpt-4o

deimos

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_API_KEY="sk-your-key-here"
$env:OPENAI_MODEL="gpt-4o"

deimos

Fastest local Ollama setup

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b

deimos

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_BASE_URL="http://localhost:11434/v1"
$env:OPENAI_MODEL="qwen2.5-coder:7b"

deimos

Setup guides

Index: docs/README.md · Checklist: docs/setup-checklist.md · After install: docs/first-run.md · Problems: docs/troubleshooting.md

Beginner-friendly:

• Non-technical setup
• Windows quick start
• macOS / Linux quick start

Advanced / source build:

• Advanced setup — Bun, profiles, doctor:*, env table
• .env.example — template in git; copy to .env for a local clone, uncomment one provider block (see file header)
• Android (Termux) — build inside proot Ubuntu

Optional: python/ — small Python helpers for experiments; not required for normal CLI install (python/README.md).

Supported providers

What works

• Tool-driven coding workflows: Bash, file read/write/edit, grep, glob, agents, tasks, MCP, and slash commands
• Streaming responses: Real-time token output and tool progress
• Tool calling: Multi-step tool loops with model calls, tool execution, and follow-up responses
• Images: URL and base64 image inputs for providers that support vision
• Provider profiles: Guided setup plus saved .deimos-profile.json support
• Local and remote model backends: Cloud APIs, local servers, and Apple Silicon local inference

Provider notes

Deimos supports multiple providers, but behaviour is not identical across all of them.

• Anthropic-specific features may not exist on other providers
• Tool quality depends heavily on the selected model
• Smaller local models can struggle with long multi-step tool flows
• Some providers impose lower output caps than the CLI defaults, and Deimos adapts where possible

For best results, use models with strong tool/function calling support.

Agent routing

Deimos can route different agents to different models through settings-based routing. This is useful for cost optimisation or splitting work by model strength.

Add to ~/.claude/settings.json:

{
  "agentModels": {
    "deepseek-chat": {
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "sk-your-key"
    },
    "gpt-4o": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-key"
    }
  },
  "agentRouting": {
    "Explore": "deepseek-chat",
    "Plan": "gpt-4o",
    "general-purpose": "gpt-4o",
    "frontend-dev": "deepseek-chat",
    "default": "gpt-4o"
  }
}

When no routing match is found, the global provider remains the fallback.

api_key values in settings.json are plaintext. Don’t commit that file.

Web search and fetch

By default, WebSearch works on non-Anthropic models using DuckDuckGo. This gives GPT-4o, DeepSeek, Gemini, Ollama, and other OpenAI-compatible providers a free web search path out of the box.

DuckDuckGo fallback scrapes search results; it can be rate-limited or blocked. For something sturdier, wire up Firecrawl below.

For Anthropic-native backends and Codex responses, Deimos keeps the native provider web search behaviour.

WebFetch works, but its basic HTTP plus HTML-to-markdown path can still fail on JavaScript-rendered sites or sites that block plain HTTP requests.

Set a Firecrawl API key if you want Firecrawl-powered search/fetch behaviour:

export FIRECRAWL_API_KEY=your-key-here

With Firecrawl enabled:

• WebSearch can use Firecrawl's search API while DuckDuckGo remains the default free path for non-Claude models
• WebFetch uses Firecrawl's scrape endpoint instead of raw HTTP, handling JS-rendered pages correctly

Free tier at firecrawl.dev includes 500 credits. The key is optional.

Headless gRPC server

Deimos can be run as a headless gRPC service, so you can integrate its agentic capabilities (tools, bash, file editing) into other applications, CI/CD pipelines, or custom user interfaces. The server uses bidirectional streaming to send real-time text chunks, tool calls, and request permissions for sensitive commands.

Start the gRPC server

Start the core engine as a gRPC service on localhost:50051:

npm run dev:grpc

Configuration

Run the test CLI client

We provide a lightweight CLI client that communicates exclusively over gRPC. It acts just like the main interactive CLI, rendering colors, streaming tokens, and prompting you for tool permissions (y/n) via the gRPC action_required event.

In a separate terminal, run:

npm run dev:grpc:cli

Note: the gRPC definitions live in src/proto/deimos.proto.

Source build and local development

bun install
bun run build
node dist/cli.mjs

From a clone: create .env from .env.example, uncomment one provider block, put real values in .env (the example file header explains the fields).

Bun is what the repo scripts expect. Common commands:

• bun run typecheck
• bun run dev
• bun test
• bun run test:coverage
• bun run security:pr-scan -- --base origin/main
• bun run smoke
• bun run doctor:runtime
• bun run verify:privacy
• focused bun test ... for the areas you touch

Tags: pushing a v* tag runs release artefacts (uploads dist/cli.mjs as a CI artefact). Maintainer checklist: docs/maintainers.md.

Testing and coverage

Tests use Bun’s built-in runner.

bun test

Coverage (writes coverage/lcov.info and a heatmap at coverage/index.html):

bun run test:coverage

Open the HTML report: macOS / Linux open coverage/index.html — Windows PowerShell: start coverage/index.html.

Rebuild only the coverage UI from an existing lcov.info:

bun run test:coverage:ui

Targeted runs:

• bun run test:provider
• bun run test:provider-recommendation
• bun test path/to/file.test.ts

Before opening a PR, a sensible smoke pass is bun run build, bun run smoke, then either focused bun test … on what you touched or bun run test:coverage if you changed shared runtime or provider code.

Repository structure

The CLI is built from src/ into dist/cli.mjs; bin/deimos.mjs is the published entrypoint npm calls. Everything else is documentation, build/CI tooling, the VS Code add-on, optional python/ helpers, or policy files at the repo root — each path is described under Paths below.

Layout

flowchart TB
  subgraph DOC[Documentation]
    direction LR
    D1[docs/]
    D2[README.md]
    D3[ANDROID_INSTALL.md]
  end
  subgraph AGENT[Terminal agent]
    direction LR
    A1[src/]
    A2[bin/]
    A3[package.json]
    A4[tsconfig.json]
  end
  subgraph OUT[Build output]
    O1[dist/cli.mjs]
  end
  subgraph META[Tooling and meta]
    direction LR
    M1[scripts/]
    M2[vscode-extension/]
    M3[python/]
    M4[.github/]
    M5[.env]
  end
  AGENT --> OUT

.env is what you edit on your machine (gitignored). .env.example is only the checked-in template — copy it to .env once, then change .env, not the example file.

Clone vs npm install

A full git clone matches the chart. npm install -g @dxa-dev/deimos (npm package) only unpacks what package.json lists under "files" — right now bin/, dist/cli.mjs, and README.md.

flowchart LR
  subgraph CLONE[Git clone]
    C1[entire repo]
  end
  subgraph NPM[npm package]
    direction TB
    N1[bin/]
    N2[dist/cli.mjs]
    N3[README.md]
  end

Paths

Documentation

• docs/ — User guides: index, checklist, first run, troubleshooting
• ANDROID_INSTALL.md — Build inside Termux / proot Ubuntu
• README.md — Project overview (also included in the npm tarball)

Terminal agent

• src/ — Core CLI and runtime (providers, tools, MCP, UI)
• bin/ — deimos.mjs launcher (npm exposes the deimos command; runs dist/cli.mjs when built)
• package.json — Metadata, scripts, and the published files list
• tsconfig.json — TypeScript project for src/

Build and checks

• scripts/ — Build pipeline, doctor:*, security scans, coverage helpers

Editor add-on

• vscode-extension/deimos-vscode/ — VS Code integration and terminal theme (extension readme)

Optional

• python/ — Optional utilities (python/README.md); not required for the CLI

Repository / CI

• .github/ — PR checks, v* release artefacts, Dependabot, issue/PR templates
• .env — Your provider keys when working from a clone (gitignored). Duplicate .env.example to .env, then edit .env only (cp .env.example .env on Unix; Copy-Item .env.example .env in PowerShell).
• .env.example — Reference template in the repo; do not put secrets here.
• Root — CONTRIBUTING.md, CHANGELOG.md, LEGAL.md, LICENSE, SECURITY.md

VS Code extension

vscode-extension/deimos-vscode/: launch the CLI from the editor, Control Centre in the activity bar, bundled terminal theme. Extension readme.

Security

If you believe you found a security issue, see SECURITY.md.

Community

• Discussions — questions, ideas, general chat
• Issues — bugs and concrete feature requests

Contributing

CONTRIBUTING.md covers clone, bun install, build, and what CI expects. Big or ambiguous changes: open an issue before a huge PR.

Legal / trademarks

MIT applies to material in this repository; dependencies have their own licences. Third-party names appear only where descriptive (see LEGAL.md). Full licence text: LICENSE. Not legal advice—consult a solicitor or other qualified legal adviser if you need a formal opinion.

Links