demian-cli 1.0.3

package/README.md

@@ -0,0 +1,374 @@
+# Demian TUI
+
+<p>
+  <img src="./media/demian.svg" width="72" height="72" alt="Demian icon">
+</p>
+
+**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: [한국어](./docs/ko/README.md)
+
+## 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
+
+```sh
+npm install -g demian-cli
+```
+
+Then open a project and start the TUI:
+
+```sh
+cd ~/work/my-project
+demian
+```
+
+You can also run without installing globally:
+
+```sh
+npx demian
+```
+
+## Quickstart
+
+1. Open your project:
+
+   ```sh
+   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:
+
+   ```text
+   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.
+
+### OpenAI-Compatible Example
+
+Create `~/.demian/config.jsond`:
+
+```jsonc
+{
+  "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:
+
+```sh
+export OPENAI_API_KEY="..."
+demian --provider openai --model gpt-5.5
+```
+
+### Local Model Example: Ollama
+
+```sh
+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:
+
+```sh
+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:
+
+   ```text
+   Find how authentication is wired in this project.
+   ```
+
+2. Ask for a focused change:
+
+   ```text
+   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:
+
+   ```text
+   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.
+
+```sh
+demian '/goal Update the README, run the checks, and finish only after verification passes.'
+```
+
+Inside an interactive session:
+
+```text
+/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.
+
+```text
+/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.
+
+```sh
+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
+
+```sh
+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.
+- `/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:
+
+```sh
+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:
+
+```sh
+demian --no-persistent-grants
+```
+
+## Web Search
+
+Demian supports Brave, Tavily, and Exa through the `web_search` tool.
+
+```jsonc
+{
+  "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:
+
+```sh
+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:
+
+```sh
+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`.
+
+```sh
+~/.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