Node.js 20.19+ or 22.12+ is required.

Run from source:

git clone https://github.com/tree201/do-code.git
cd do-code
npm install
npm run build:agent
npm link

Then start in an existing project:

cd /path/to/your-project
do-code auth
do-code

do-code auth guides you through provider setup. API keys are stored only in local user configuration; environment variables override saved values.

• Works in real repositories — read and attach files, edit code, run shell commands, inspect Git diffs, and run tests.
• Uses your model provider — built-in setup for Volcengine Ark, Alibaba ModelStudio, DeepSeek, MiniMax, Z.AI, and ModelScope; Custom Provider supports OpenAI-compatible, Anthropic, and Gemini APIs.
• Keeps execution controlled — planning and permission modes are independent, and built-in file edits and patches receive local checkpoints for inspection or recovery.

Type / to browse commands and @ to attach workspace files:

/plan · /permissions · /model · /resume
/status · /stats · /compact · /diff
/memory · /rewind · /export · /language
@src/app.ts           Add a file to the current context
!npm test             Run a command under the current permission mode

Use /thinking and /effort to tune reasoning during a session; add --persist to save the choice as the default for future sessions. The interface supports English, Simplified Chinese, Japanese, Korean, Spanish, and French through --language or /language.

• Keep working while a task runs — queued prompts now remain directly above the composer, ready to review or recall with ↑.
• Handle large paste safely — long pasted text folds into a compact preview in the composer instead of pushing the input surface away.
• Read terminal Markdown reliably — long inline code, URLs, unspaced CJK text, and emoji wrap by terminal display width without losing content.
• Keep approval intent with the work — each session remembers its approval mode; use the left-hand Ctrl+G shortcut to change it while working.
• Keep long tasks focused — compaction retains a rolling summary plus recent complete task turns, so the active work stays in context while older work is summarized in batches.
• Resume from a short working note - when a task needs durable progress across steps, the agent maintains a task note with the goal, progress, evidence, blockers, and next step, stored outside the workspace.

do-code
do-code --continue
do-code resume <session-id>

Continue the latest project session with do-code --continue, or choose one with resume and /resume:

do-code sessions list
do-code sessions search "authentication"
do-code sessions rename <session-id> "Auth cleanup"
do-code sessions delete <session-id>
do-code sessions export <session-id> md ./session.md

Use /stats to inspect context use and /compact to compact it on demand. Near the context limit, do-code summarizes older complete turns in batches while retaining a rolling summary and the recent complete task queue. For work that needs a durable handoff, the agent can maintain a short task note; do-code refreshes it before each model request.

Layered AGENTS.md instructions follow the workspace hierarchy; inspect or reload them with /memory. Start an isolated Git worktree with do-code --worktree or do-code --worktree=<name>, and inspect do-code worktrees with do-code worktrees.

Agent profiles can select a model, approval mode, instructions, step limit, and tool allow/deny lists. Inspect them with do-code agents and select one with do-code --agent <name>. Browse Markdown commands and skills with /extensions; use do-code extensions for a summary of commands, skills, and configured MCP servers.

run produces stable JSON or JSONL output for automation. Tasks can come from an argument or --task-file; --max-steps and --timeout set execution budgets. --artifact-dir stores the frozen configuration, event stream, result, and patch artifacts.

do-code run --yes --output-format stream-json \
  --task-file task.txt --artifact-dir ./artifacts \
  --max-steps 40 --timeout 600

Use do-code acp for the ACP standard input/output protocol. See the Headless / JSONL protocol for the supported automation contract.

Attach up to four PNG, JPEG, GIF, or WebP images with repeated --image in headless mode. The selected model must support image input.

do-code run --image screenshots/bug.png --image screenshots/diagram.webp "Describe these images"

In the interactive TUI, press Ctrl+V to paste an image from the system clipboard, or type @path/to/image.png to add one from a file. To remove a pending attachment, place the cursor on its image tag/token in the editor and press Backspace. Each image is limited to 10 MB and the prompt total is limited to 20 MB. Imported files are copied to ~/.local/share/do-code/projects/<project-key>/sessions/<session-id>/attachments/; persisted messages contain only relative references such as attachments/image_xxx.png, never Base64 data or the original absolute path. Set DO_CODE_DATA_DIR to override the global data root. Existing project-local .do-code data is migrated to the user-managed project directory when the project is next accessed.

do-code config show          # Inspect effective model configuration
do-code doctor               # Check model, workspace, and local tools
do-code sessions list        # List project sessions
do-code extensions           # Inspect commands, skills, and MCP configuration
do-code agents               # List agent profiles
do-code worktrees            # List isolated worktrees
do-code errors list          # List recent error reports

The default Ask mode requests confirmation for high-risk actions. Auto handles ordinary workspace changes automatically. Full Access is intended only for trusted workspaces or CI.

Configuration is stored under ~/.config/do-code/; project sessions, attachments, checkpoints, and error reports are stored under ~/.local/share/do-code/projects/<project-key>/. DO_CODE_DATA_DIR overrides the data root. Credentials and project data stay on your machine by default.

Sandbox settings can use local execution, macOS Seatbelt, or a container, depending on configuration and host support. Permission mode and sandbox configuration are separate controls.

To inspect a failure:

do-code errors list
do-code errors show <error-id>

• Documentation index
• Bad case feedback and diagnostics
• Headless / JSONL protocol
• Architecture
• Local development
• Personal release process

Issues and pull requests are welcome. Please read the contributing guide and security policy before submitting a change.

npm run verify:local
npm run build:agent

Apache-2.0