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 Ink TUI with provider, model, agent, 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.

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, apiKeyEnv, 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.

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-4-6

Available Claude Code model aliases in the default config:

• claude-sonnet-4-6
• claude-opus-4-7

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 Ink 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 claudecode --model claude-sonnet-4-6
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"

Inside the TUI:

• 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>]
demian config path
demian auth login codex
demian auth login claudecode
demian auth status

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 API key environment variable. You can override the model at launch:

demian --provider openai --model gpt-5.5

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