Demian TUI

Demian is a local terminal coding agent for developers. It can inspect a workspace, answer code questions, edit files, run commands with approval, keep longer goals alive, and coordinate multiple sub agents when a task benefits from parallel research or review.

Default language: English
Additional locale: 한국어

Highlights

• Interactive Bubble Tea TUI with provider, model, agent, session, and permission controls.
• Plain CLI mode for scripts, pipes, and terminals that cannot run the TUI.
• Local workspace tools: read, glob, grep, write, edit, bash, update plan, web search, progress reporting, and cowork delegation.
• Goal mode with /goal for longer objectives that should be verified before completion.
• Cowork mode with /cowork for bounded multi-agent coordination, including a Codex-manager and Claude-Code-worker routing preset.
• Provider support for OpenAI-compatible APIs, Anthropic API, Codex, Claude Code, Ollama, LM Studio, vLLM, llama.cpp, OpenRouter, Together, Groq, Gemini, and Azure OpenAI-compatible endpoints.
• Permission prompts for side effects, with optional persistent "always allow" grants.
• Project and user configuration through .demian/config.json or .demian/config.jsond.
• First-run setup plus terminal config screens and demian config commands for provider defaults, connection fields, and model profiles.

Requirements

• Node.js 22.18 or newer.
• At least one model provider configured.
• Optional: Claude Code installed locally if you want to use the claudecode provider.
• Optional: Antigravity CLI installed locally if you want to use the antigravity-cli provider with a Google account login.

Install

npm install -g demian-cli

Then open a project and start the TUI:

cd ~/work/my-project
demian

You can also run without installing globally:

npx demian

Quickstart

1. Open your project:

   cd ~/work/my-project
   demian

2. Choose a provider and model before your first message.

   In the TUI:

   • Press Esc then k to open the command palette.
   • Press Esc then s to select a saved session.
   • Press Esc then p to choose a provider.
   • Press Esc then m to edit the model.
   • Press Esc then a to choose the main agent.
   • Press Esc then c to open the config screen for persistent provider/model setup.
   • In the config screen, press w to tune cowork providers, routing, fallback, and permission defaults.
   • Type your request and press Enter.

3. Try a first prompt:

   Summarize this repository and tell me where the main entry points are.

4. When Demian asks for permission, review the requested command or file operation:

   • y: allow once
   • a: always allow this grant scope
   • n or Enter: deny

5. Keep chatting. Demian keeps conversation history while the session is open. Use /compact when the conversation gets long, and /exit when you are done.

Provider Setup

Demian loads configuration from user and project locations:

1. built-in defaults
2. ~/.demian/config.json
3. ~/.demian/config.jsond
4. .demian/config.json in the working directory
5. .demian/config.jsond in the working directory
6. --config <path>
7. .demian/preferences.json
8. CLI flags

.jsond files support comments and trailing commas.

The terminal UI creates ~/.demian/config.json automatically when no user config exists. Press Esc then c to open the config screen. From there you can set the default provider, choose or add a default model profile for a provider, edit the selected provider's baseURL, API key env or OAuth token/project env fields, and auth header, add common provider presets, and tune cowork provider routing without hand-editing JSON.

OpenAI-Compatible Example

Create ~/.demian/config.jsond:

{
  "defaultProvider": "openai",
  "providers": {
    "openai": {
      "type": "openai-compatible",
      "baseURL": "https://api.openai.com/v1",
      "apiKey": "",
      "apiKeyEnv": "OPENAI_API_KEY",
      "modelProfiles": [
        { "name": "main", "displayName": "GPT 5.5", "model": "gpt-5.5" }
      ]
    }
  }
}

Then export your key:

export OPENAI_API_KEY="..."
demian --provider openai --model gpt-5.5

Providers that can expose many local or self-hosted models, such as lmstudio, ollama-local, ollama-cloud, llamacpp, and vllm, also use modelProfiles. Add one array entry per model you want to show in the model selector.

Multiple Codex accounts

Each named Codex provider can use its own CODEX_HOME. In the TUI, open configuration with Esc, then c. Select Codex and press c again to add an account such as work; Demian registers it as codex-work. Press l to sign in, h to connect an existing authentication directory, or m to load models with that account. Select codex-work in the provider picker to use it.

The same operations are available from the terminal:

demian config add-provider codex --name codex-work
demian auth login codex-work
demian auth status codex-work
demian --provider codex-work

# Register an existing account directory without copying its credentials.
demian config add-provider codex --name codex-personal --codex-home ~/.codex-personal

Without --codex-home, additional profiles use accounts/codex/<name> beside the config file (~/.demian/accounts/codex/codex-work by default). Demian creates new directories with mode 0700; Codex stores its credentials in auth.json. These profiles use file authentication and disable API-key fallback. The original codex profile keeps its existing home and auth-store settings. For a custom config, use --path <file> when editing and --config <file> when logging in, checking status, or starting Demian.

Account names are provider profile names, so agents and delegate_agent can select codex-work and codex-personal independently, with separate credentials and model catalogs. For example: "Ask codex-work to analyze the backend and codex-personal to review the findings." This manages local TUI/CLI profiles; it does not add multiple personal connections to the Web account API or isolate accounts into separate OS users. Keep authentication directories out of source control; the config stores paths, not tokens.

Claude Code accounts and Antigravity profiles

In TUI configuration, select Claude Code or Antigravity and press c to add a named profile. h edits its directory, x selects its CLI executable, and m selects its model. Claude Code's l starts browser sign-in; Antigravity's l shows the terminal sign-in command and the credential-store limitation.

demian config add-provider claudecode --name claudecode-work
demian auth login claudecode-work
demian auth status claudecode-work
demian --provider claudecode-work

# Connect an existing Claude Code account directory.
demian config add-provider claudecode --name claudecode-personal --claude-config-dir ~/.claude-personal

demian config add-provider antigravity-cli --name antigravity-work
demian config update-provider antigravity-work --cli-path /absolute/path/to/isolated-agy
demian auth login antigravity-work
demian --provider antigravity-work

Named Claude profiles use accounts/claudecode/<name> beside the Demian config file. Login, authentication checks, SDK execution, and model discovery receive the same CLAUDE_CONFIG_DIR. New profiles clear conflicting OAuth-token, API-key, and cloud-backend environment overrides. Claude owns credential storage and refresh, including its macOS Keychain integration. Use a current Claude CLI that supports CLAUDE_CONFIG_DIR account isolation and auth status --json.

Named Antigravity profiles use accounts/antigravity/<name> as their child process's HOME; --antigravity-home connects an existing directory. This separates settings and history. Antigravity OAuth accounts are not isolated by HOME: the installed CLI uses the OS keyring and does not expose an auth profile selector. Separate accounts require a wrapper that runs agy under a separate OS user or container with its own credential store. Point cliPath at that wrapper; it must forward arguments, input/output, exit codes, and the workspace to agy. Demian uses the same executable and environment for sign-in and execution; it does not provision that external environment or swap keyring entries. Until the wrapper is configured, profiles share the OS keyring. auth status reports Antigravity OAuth as unverified (exit 1), even if the CLI is installed. Its model list still comes from configured presets.

These profile names can also be selected in agent settings and natural-language delegation from a Demian coordinator. Runtime profiles are passed to each child independently. Process environment variables on the host are not changed. For parallel cowork execution, include the profiles in cowork.providers using w in TUI configuration.

References: Claude environment variables, Antigravity authentication, Antigravity auth profile feature request.

Gemini: API Key, API OAuth, or Antigravity CLI

The default gemini provider uses Gemini's OpenAI-compatible endpoint and GEMINI_API_KEY or GOOGLE_API_KEY.

If you want the Google account based CLI path, install the official Antigravity CLI, complete sign-in there, then use Demian's antigravity-cli external runtime provider:

curl -fsSL https://antigravity.google/cli/install.sh | bash
demian auth login antigravity-cli
demian config add-provider antigravity-cli --name antigravity-cli --force
demian --provider antigravity-cli --model gemini-3.1-pro-high

antigravity-cli runs the local agy binary in headless stream-json mode. Demian keeps API-key and Vertex AI environment variables visible by default because Antigravity CLI also supports those modes. Set sanitizeApiKeyEnv: true on the provider if you want Demian to hide them from the child process.

Existing gemini-cli configs are treated as a legacy alias and are migrated to the Antigravity CLI runtime when loaded.

If you want Gemini API OAuth/ADC instead of the subscription CLI path, use the native gemini-oauth provider:

demian auth login gemini --client-id-file ~/Downloads/client_secret.json
export GOOGLE_CLOUD_PROJECT="your-google-cloud-project"
demian config add-provider gemini-oauth --name gemini-oauth --force
demian --provider gemini-oauth --model gemini-2.5-pro

Create a Desktop app OAuth client in Google Cloud, download its client_secret.json, and pass it with --client-id-file. This avoids Google's "This app is blocked" response that can appear when the default gcloud OAuth app requests Gemini scopes. demian auth login gemini still runs Google application-default login; at runtime, Demian reads GOOGLE_OAUTH_ACCESS_TOKEN if set, otherwise it asks gcloud auth application-default print-access-token for a bearer token. GOOGLE_CLOUD_PROJECT is used as the Gemini OAuth quota project header.

Local Model Example: Ollama

brew install ollama
ollama serve
ollama pull qwen2.5-coder:latest
demian --provider ollama --model qwen2.5-coder:latest

Anthropic API vs Claude Code

Demian has two Claude-related paths:

• anthropic: direct Anthropic API provider. It uses ANTHROPIC_API_KEY and Anthropic API billing.
• claudecode: external Claude Code runtime. It uses your local Claude Code installation and login/subscription path through the Claude Agent SDK. The default CLI path is ~/.local/bin/claude.

Use anthropic when you want direct API-key calls. Use claudecode when you want Demian to coordinate Claude Code as an external agent runtime.

Example:

demian --provider claudecode --model claude-sonnet-5

Available Claude Code model aliases in the default config:

• claude-sonnet-5
• claude-opus-5
• claude-fable-5
• claude-haiku-4-5-20251001

Tutorial: Ask, Edit, Verify

This is the normal Demian loop.

1. Ask Demian to inspect the project:

   Find how authentication is wired in this project.

2. Ask for a focused change:

   Add a validation error when the email is missing. Keep the change minimal.

3. Review permission prompts. Demian will ask before running commands or making side-effecting changes unless your policy already allows them.

4. Ask Demian to verify:

   Run the relevant tests and summarize what changed.

5. Use /compact if you want to keep the session but shrink older context.

Goal Mode

Use /goal when the task should stay active until it is verified and completed.

demian '/goal Update the README, run the checks, and finish only after verification passes.'

Inside an interactive session:

/goal Fix the flaky login test and verify it locally.

Useful goal commands:

• /goal status: show the active goal.
• /goal pause: pause it.
• /goal resume: continue it.
• /goal clear: archive it.

Goal state is stored under .demian/goals/. Completion is accepted only when Demian marks the goal complete after verification.

Cowork Mode

Use /cowork when Demian should coordinate multiple bounded sub agents and synthesize their results.

/cowork Have one agent inspect the API layer and another inspect the UI flow. Compare the risks and recommend the smallest fix.

Demian remains the main coordinator. Sub agents are workers with bounded tasks. The default cowork settings allow read-only parallelism and keep writer coordination conservative.

By default, cowork routing favors Codex-backed agents for planning, architecture, research synthesis, and supervisory review. It favors Claude-Code-backed agents for bounded implementation, module-level development, detailed code review, and specialist work in the local repo. You can tune this split from the TUI config screen: press Esc, then c, then w.

The main cowork settings are:

• cowork.providers: providers that are allowed to participate in cowork runs.
• cowork.routing.agentProviders: provider priority per agent role.
• cowork.fallback.nonWrite: fallback behavior for read-only, review, and manage work.
• cowork.fallback.write: write repair behavior. Write tasks do not automatically switch providers after partial side effects; Demian rereads changed files and retries repair with the same agent/provider when configured.
• cowork.permissionOverlay: Demian-managed permission defaults that compile into provider runtime tool permissions.

Cowork is most useful for:

• comparing two implementation paths
• asking one agent to inspect while another verifies
• combining Codex-style and Claude Code-style agent work
• separating planning, review, and implementation roles

Plain CLI

Use demian-plain when you need raw Markdown output, scripting, or a terminal that cannot render the Bubble Tea TUI.

demian-plain "Explain the project structure"
demian-plain --provider ollama --model qwen2.5-coder:latest "Review this folder"
demian-plain --image screenshot.png "What UI issue do you see?"

Plain mode supports the same core provider, goal, image, sandbox, and permission flags.

Common Commands

demian                                  # open the TUI
demian --provider openai --model gpt-5.5
demian --provider codex --model gpt-5.6-sol
demian --provider claudecode --model claude-sonnet-5
demian --single-agent
demian --multi-agent
demian --sandbox read-only
demian --sandbox workspace-write
demian --image screenshot.png
demian-plain "Give me a release checklist"

Multi-agent mode is enabled by default in both the TUI and plain CLI. You can ask for delegation in ordinary language; /cowork is an optional shortcut. For example, with Codex as the main provider: "Have Claude Code analyze the frontend and Codex analyze the backend, then have Codex synthesize the results." Demian supplies delegate_agent and cowork to the coordinator, including per-task provider/model selection. Simple tasks can still be handled directly.

Use --single-agent or agentMode: "single-agent" in the config to disable Demian delegation. The TUI header shows the active mode. Mixed-provider coordination requires a Demian tool-aware main provider such as Codex or OpenAI-compatible; Claude Code and Antigravity external runtimes can run as delegated workers, but their main sessions do not currently expose Demian orchestration tools.

Inside the TUI:

• Drag across output and release to copy the selected text. Ctrl+C copies the current selection again; Esc clears it. Mouse-wheel and PageUp/PageDown scrolling remain available. Local clipboard helpers are used alongside OSC52 for terminals and SSH sessions that support it.

• Paste +./src/main.ts or type + before pasting a file path to attach the file. Quoted paths such as +"/path/to/my file.png", shell-escaped spaces, ~/..., file://..., and multiple paths are supported. A typed +path is attached on Enter; Enter again sends the message. @ references keep their existing meaning.

• Attachments appear above the composer. Backspace on an empty composer removes the last attachment; clearing the composer removes all attachments. UTF-8 text/source files and PNG/JPEG/GIF/WebP images are supported, up to 8 files and 16 MiB total (1 MiB per text file, 8 MiB per image). Text contents are included in the request; images use native image input, including Claude Code Agent SDK. Other external CLI runtimes retain their configured attachment fallback.

• Esc then k: open the command palette.

• Esc then s: select a saved session.

• Esc then p: choose a provider.

• Esc then m: edit the model.

• Esc then a: choose the main agent.

• Esc then o: choose the default permission preset.

• Esc then c: configure provider defaults and model profiles.

• Esc then u: clear the composer.

• Esc then q: quit.

• /compact: summarize older conversation history.

• /session list: show saved CLI conversations.

• /session new [title]: start a fresh conversation.

• /session switch <number|id|title>: switch to a saved conversation.

• /session rename <title> and /session delete <number|id|title>: manage conversations.

• /stop: stop active work.

• /exit or /quit: close Demian.

• /goal ...: start a verified long-running objective.

• /cowork ...: explicitly coordinate cowork sub agents.

Config and auth helpers:

demian config setup
demian config init [--path ~/.demian/config.json] [--provider openai]
demian config list
demian config models <provider> [--refresh]
demian config add-provider <preset|openai-compatible> [--name <name>]
demian config add-model <provider> --name <name> --model <model>
demian config set-default-model <provider> [--profile <name> | --model <model>]
demian config update-provider <provider> [--base-url <url>] [--api-key-env <env>] [--access-token-env <env>] [--project-id-env <env>] [--cli-path <path>] [--permission-mode <mode>] [--effort <low|medium|high>]
demian config agents [--manage]
demian config add-agent <name> --description <text> --provider <name> [--model <id>] --instruction <text>
demian config update-agent <name> [--provider <name>] [--model <id>] [--instruction <text>]
demian config remove-agent <name>
demian config path
demian auth sign-in codex
demian auth sign-in claudecode
demian auth sign-in gemini
demian auth sign-in gemini-antigravity
demian auth status

demian config agents --manage opens the interactive agent-profile manager. Each user agent stores a name, description, provider, model, and identity instruction. The older auth login spelling remains supported.

Tools and Permissions

Demian can use local tools for code work:

• read_file, glob, grep
• write_file, edit_file
• bash
• web_search
• update_plan
• cowork
• delegate_agent

Side effects are permission-controlled. The default sandbox is workspace-write. You can change it per run:

demian --sandbox read-only
demian --sandbox off

"Always allow" grants are persisted by default according to Demian's grant policy. Use this for one-off sessions:

demian --no-persistent-grants

Web Search

Demian supports Brave, Tavily, and Exa through the web_search tool.

{
  "webSearch": {
    "defaultProvider": "brave",
    "providers": {
      "brave": {
        "apiKey": "",
        "apiKeyEnv": "BRAVE_SEARCH_API_KEY"
      },
      "tavily": {
        "apiKey": "",
        "apiKeyEnv": "TAVILY_API_KEY"
      },
      "exa": {
        "apiKey": "",
        "apiKeyEnv": "EXA_API_KEY"
      }
    }
  }
}

Web search asks for permission because it may call paid third-party APIs.

Where Demian Stores Data

Demian uses both user-level and project-level storage:

• ~/.demian/config.json or ~/.demian/config.jsond: user config.
• ~/.demian/conversations.json and ~/.demian/conversations/: saved CLI and VS Code conversations.
• .demian/config.json or .demian/config.jsond: project config.
• .demian/preferences.json: remembered provider/model choice for the current workspace.
• .demian/grants.json: persistent permission grants.
• .demian/goals/: active and archived goal state.
• .demian/: transcripts and workspace-scoped runtime files.

Leave apiKey empty and prefer apiKeyEnv for shared project config. Paste into apiKey only for local private config.

Troubleshooting

demian says the TUI requires an interactive terminal

Use a real terminal or run plain mode:

demian-plain "Summarize this repository"

A provider loads but the model fails

Check the provider's model, baseURL, and auth environment variable. For Gemini OAuth, also check GOOGLE_CLOUD_PROJECT or the configured projectIdEnv. You can override the model at launch:

demian --provider codex --model gpt-5.6-sol

Claude Code does not start

Check that Claude Code is installed and that the configured cliPath exists. The default path is ~/.local/bin/claude.

~/.local/bin/claude --version

Cowork does not choose the provider you expected

Open the TUI config screen with Esc, then c, then w. Check that the provider is included in cowork.providers, then check the agent-specific routing order. If a write task fails after partial file changes, Demian keeps the same provider and uses the write repair policy instead of falling through to another provider.

Permission prompts feel too frequent

Use a to always allow a specific grant scope, or configure a project policy. Use --no-persistent-grants when you do not want "always allow" grants saved.

License

Apache-2.0