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.
• 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.

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

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 p to choose a provider.
   • Press m to edit the model.
   • Press a to choose the main agent.
   • 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.

   To attach local context in the TUI, run /attach <path> before your next message. @ works as a lightweight file reference marker, so /attach @src/app.ts @docs/spec.md attaches both files to the next prompt. Use /attach clear to remove pending attachments.

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.

OpenAI-Compatible Example

Create ~/.demian/config.jsond:

{
  "defaultProvider": "openai",
  "providers": {
    "openai": {
      "type": "openai-compatible",
      "baseURL": "https://api.openai.com/v1",
      "apiKeyEnv": "OPENAI_API_KEY",
      "model": "gpt-5.5"
    }
  }
}

Then export your key:

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

Attachment Limits

Demian limits each local attachment before it is copied into a workspace cache or converted into model input. The default is 20 MB per attachment.

Configure it in any Demian config file:

{
  "multimodal": {
    "maxAttachmentBytes": 20971520
  }
}

maxAttachmentBytes applies to VS Code file attachments, pasted clipboard files, TUI /attach files, and image inputs. maxImageBytes is still accepted as a more specific legacy override for image conversion, but new configs should prefer maxAttachmentBytes.

The 20 MB default is intentionally conservative across providers. Current published limits are higher for OpenAI image inputs and for Anthropic's direct Claude API standard endpoints, while some Claude partner-operated platforms can be closer to 20 MB.

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.

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:

• /compact: summarize older conversation history.
• /stop: stop active work.
• /exit or /quit: close Demian.
• /attach <path> or /attach @path: attach a file to the next message.
• /attach clear: remove pending TUI attachments.
• /goal ...: start a verified long-running objective.
• /cowork ...: explicitly coordinate cowork sub agents.

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": {
        "apiKeyEnv": "BRAVE_SEARCH_API_KEY"
      },
      "tavily": {
        "apiKeyEnv": "TAVILY_API_KEY"
      },
      "exa": {
        "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/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.

Do not store API keys in shared project config. Prefer apiKeyEnv.

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

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