kodo

kodo 是一個面向程式碼倉庫的輕量本地 coding agent。它直接跑在終端機裡，先看目前工作區，再用一組受約束的工具去讀檔案、改檔案、跑命令，並把會話狀態保存在本地 .kodo/ 目錄裡。

它更像一個能在倉庫裡持續工作的命令列助手，不是純聊天視窗。你可以拿它做程式碼排查、測試修復、倉庫分析，或者讓它在目前專案裡執行一次性的工程任務。

適合做什麼

• 在本地倉庫裡排查測試失敗
• 讀取目前程式碼結構並給出修改建議
• 基於現有檔案做小步迭代，而不是脫離倉庫空想
• 在會話中保留上下文，支援繼續上一次工作

主要特性

• 套件名稱是 kodo
• CLI 命令是 kodo
• 模組入口是 python -m kodo
• 會話保存在 .kodo/sessions/
• 每次執行的工件保存在 .kodo/runs/<run_id>/
• 支援三類模型後端：
  • Ollama
  • OpenAI 相容 Responses API
  • Anthropic 相容 Messages API

使用截圖

CLI 說明資訊：

啟動介面：

REPL 內建命令與會話路徑：

安裝

需要 Python 3.10+。

方式一：使用 Python 虛擬環境

在 Windows PowerShell 裡：

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .

啟動 kodo：

python -m kodo

也可以執行一次性任務：

python -m kodo "inspect the test failures and propose a fix"

方式二：使用 uv

如果已經安裝了 uv，可以直接同步環境：

uv sync

快速開始

kodo 有兩種常用啟動方式。

用模組入口啟動

適合沒有安裝 uv，或者已經啟用 .venv 的情況：

python -m kodo

指定另一個工作目錄：

python -m kodo --cwd D:\path\to\repo

直接跑一次性任務：

python -m kodo "inspect the test failures and propose a fix"

用 uv 啟動

適合已經安裝 uv 的情況：

uv run kodo

指定另一個工作目錄：

uv run kodo --cwd /path/to/repo

直接跑一次性任務：

uv run kodo "inspect the test failures and propose a fix"

模型後端

Ollama

ollama serve
ollama pull qwen3.5:4b
uv run kodo --provider ollama --model qwen3.5:4b

OpenAI 相容介面

export OPENAI_API_BASE="https://your-api.example/v1"
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="gpt-5.4"
uv run kodo --provider openai

Anthropic 相容介面

export ANTHROPIC_API_BASE="https://www.right.codes/claude/v1"
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
uv run kodo --provider anthropic

如果你的服務端對多個相容介面複用了同一套金鑰，kodo 也支援從 ANTHROPIC_API_KEY 回退到 RIGHT_CODES_API_KEY 或 OPENAI_API_KEY。

常用互動命令

• /help：查看內建命令
• /memory：查看提煉後的工作記憶
• /session：查看目前會話檔案路徑
• /reset：清空目前會話狀態
• /exit 或 /quit：退出 REPL

安全與持久化

kodo 不會預設把所有動作都放開。像 shell 執行、檔案寫入這類高風險操作，會受審批模式控制：

• --approval ask
• --approval auto
• --approval never

每次執行結束後，都會在 .kodo/runs/<run_id>/ 下寫出這些檔案：

• task_state.json
• trace.jsonl
• report.json

這些內容預設只保存在本地，不需要跟倉庫一起提交。

評估

可以先跑單元測試確認核心行爲：

python -m pytest

如果只想快速檢查主要路徑：

python -m pytest tests/test_kodo.py tests/test_context_manager.py tests/test_memory.py tests/test_metrics.py

也可以用 kodo 自己做一次人工 smoke test：

python -m kodo "Read README.md and summarize this project in 5 bullets."

更完整的評估腳本會把結果寫到 artifacts/。先建立輸出目錄：

New-Item -ItemType Directory -Force artifacts

Provider experiments 會用真實 provider 跑 benchmarks/coding_tasks.json 裡的固定任務。它會讀取目前環境變量，也會讀取本 repo 的 .env / kodo/.env：

python scripts/run_provider_experiments.py `
  --output-json artifacts/provider-experiments.json

Resume metrics 會讀 provider benchmark 結果與 .kodo/runs，再產生 JSON 和 Markdown 報告：

python scripts/collect_resume_metrics.py `
  --benchmark-artifact artifacts/provider-experiments.json `
  --runs-root .kodo/runs `
  --provider-experiments artifacts/provider-experiments.json `
  --output-json artifacts/resume-metrics.json `
  --output-markdown artifacts/resume-metrics.md

完整 large-scale 評估會一次輸出 provider、resume、memory、context、security 和 final report：

python scripts/run_large_scale_experiments.py `
  --benchmark-artifact artifacts/provider-experiments.json `
  --runs-root .kodo/runs `
  --provider-output-json artifacts/provider-experiments.json `
  --resume-output-json artifacts/resume-metrics.json `
  --resume-output-markdown artifacts/resume-metrics.md `
  --memory-output-json artifacts/memory-metrics.json `
  --context-output-json artifacts/context-metrics.json `
  --security-output-json artifacts/security-metrics.json `
  --final-report-markdown artifacts/final-report.md

在 Windows 上，如果沒有 symlink 權限，security 評估會把 symlink case 記錄爲 symlink_unavailable，不會中斷整個評估。

開發

如果裝了 Ruff，可以這樣檢查：

uv run ruff check .