Octocode

Octocode

[](https://github.com/sievepub-2000/octocode/actions/workflows/ci.yml) [](https://opensource.org/licenses/Apache-2.0) [](https://github.com/sievepub-2000/octocode/releases) [](https://www.rust-lang.org) [](#one-line-install)

> Multi-agent open-source programming and task-execution toolkit.

> 🇯🇵 日本語の説明 → [README.ja.md](README.ja.md)

Octocode is a Rust workspace (10 crates) that ships a permission-aware runtime, pluggable provider routing (OpenAI, Gemini, DeepSeek, Qwen, Kimi, GLM, MiMo, Ollama and any OpenAI-compatible gateway), a built-in tool catalog (shell, web, files, skills, memory), session persistence, and both /metrics (Prometheus) and /api/metrics (JSON) observability. The same backend powers the CLI, a zero-build vanilla-JS WebUI, and a wry desktop shell (WebView2 on Windows, WebKit on macOS/Linux).

One-line install

The installers detect your toolchain, install rustup if needed, then run cargo install --git https://github.com/sievepub-2000/octocode --tag v2026.4.30 --locked octocode-cli. The result is the octocode-cli binary in ~/.cargo/bin (or %USERPROFILE%\.cargo\bin on Windows).

Windows (PowerShell 5.1+ or 7+):

iex (iwr -UseBasicParsing https://raw.githubusercontent.com/sievepub-2000/octocode/master/install.ps1).Content

macOS / Linux (bash / zsh):

curl -fsSL https://raw.githubusercontent.com/sievepub-2000/octocode/master/install.sh | bash

Direct (any platform with cargo already installed):

cargo install --git https://github.com/sievepub-2000/octocode --tag v2026.4.30 --locked octocode-cli

After installation:

octocode-cli doctor                 # verify environment
octocode-cli serve 999 demo         # start WebUI at http://127.0.0.1:999/ui-shell/?session=demo
octocode-cli chat demo "hello"      # one-shot CLI chat

To install the latest master instead of the tagged release, append -Master to the PowerShell command, set OCTOCODE_REF=master for the shell installer, or pass --branch master to the direct cargo command.

Quick Start (build from source)

# 1. Build the workspace
cargo build --release -p octocode-cli

# 2. Run your first chat
cargo run -p octocode-cli -- chat demo "explain what this project does"

# 3. Launch the WebUI server
cargo run -p octocode-cli -- serve 999 demo
# → open http://127.0.0.1:999/ui-shell/

# 4. Or launch the desktop app
cargo run -p octocode-cli -- desktop 999 demo

> Windows: Use scripts/start-webui.ps1 -Port 999 -SessionId demo > Unix: Use scripts/start-webui.sh 999 demo

WebUI/desktop port is restricted to 990-999.

Security model (release-hardening)

Octocode binds the WebUI to 127.0.0.1 only and gates every HTTP/WS request with a bearer token. The token is resolved with the following precedence (T1):

1. OCTOCODE_BEARER_TOKEN environment variable — preferred for production / CI.
2. OCTOCODE_BEARER_TOKEN_FILE environment variable — points to a file whose first non-empty trimmed line is the token (preferred for desktop installs).
3. Auto-generated 64-char hex secret (printed at startup). Suitable for local development only.

The startup log prints Auth token: (source: ...) so operators can confirm which path was used. All API responses now include X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer, and a Content-Security-Policy that pins script/style/connect to 'self' + 127.0.0.1 only (T14). CORS is restricted to http://127.0.0.1 rather than *.

Permission modes (permission_mode in octocode.conf): read-only, workspace-write (default), escalated. Tool execution honours denied_tools and the workspace-root file_guard.

Config file forward-compatibility: octocode.conf now records config_version=1 (T10). Older configs without the field are read as v0 and upgraded on next save.

Architecture

┌─────────────────────────────────────────────────────────┐
│                     octocode-cli                        │
│            (CLI · Server · Desktop shell)                │
├──────────┬──────────────┬──────────────┬────────────────┤
│ commands │   runtime    │     api      │    plugins     │
│ (parse)  │ (session,    │ (providers,  │ (plugin trait, │
│          │  tools,      │  circuit     │  registry)     │
│          │  workflow,   │  breaker,    │                │
│          │  permissions)│  streaming)  │                │
├──────────┴──────┬───────┴──────────────┴────────────────┤
│      core       │        mcp       │      skills       │
│  (domain types, │  (MCP discovery, │  (skill trait,    │
│   contracts)    │   transport)     │   framework)      │
└─────────────────┴──────────────────┴───────────────────┘

8 crates — core → api / mcp / skills → runtime → commands → cli

Provider Configuration

Octocode auto-creates config/octocode.conf on first run:

# Octocode config
provider_id=local-openai
provider_base_url=http://localhost:8080/v1
default_model=gpt-4
permission_mode=WorkspaceWrite
history_limit=24
denied_tools=

Supported Providers

| Provider ID | Kind | Example Base URL | |----------------|-------------------|----------------------------------------| | local-openai | LlamaCpp / OpenAI-compatible | http://localhost:8080/v1 | | remote-openai| OpenAI-compatible | https://api.openai.com/v1 | | ollama | Ollama | http://localhost:11434 | | linkmind | LinkMind | http://localhost:8765 | | gemini | OpenAI-compatible | https://generativelanguage.googleapis.com/v1 | | azure-openai | OpenAI-compatible | https://.openai.azure.com | | nvidia-free | OpenAI-compatible | https://integrate.api.nvidia.com/v1 | | anthropic | Anthropic | https://api.anthropic.com | | xai | xAI | https://api.x.ai/v1 | | openrouter | OpenRouter | https://openrouter.ai/api/v1 | | qwen | Qwen / DashScope | https://dashscope.aliyuncs.com/compatible-mode/v1 | | glm | Zhipu GLM | https://open.bigmodel.cn/api/paas/v4 | | kimi | Moonshot Kimi | https://api.moonshot.cn/v1 | | xiaomi | Xiaomi (stream) | per-deployment | | minimax | MiniMax | https://api.minimax.chat/v1 | | openai-completion | Legacy /v1/completions | self-hosted gateway | | stub | Stub (fallback) | — |

All 17 providers are described in detail under [docs/architecture.md](docs/architecture.md#3-provider-layer).

Environment Variables

| Variable | Description | Default | |-----------------------|--------------------------------------|----------------------------| | OPENAI_API_KEY | API key for OpenAI-compatible | (none) | | OCTOCODE_PROVIDER | Override default provider ID | local-openai | | OCTOCODE_BASE_URL | Override provider base URL | (from config) | | OCTOCODE_MODEL | Override default model name | (from config) |

Provider Fallback Chain

Octocode performs health checks and automatically falls back:

local-openai → remote-openai → stub

Each provider has a circuit breaker that tracks failures, with automatic recovery.

CLI Commands

| Command | Description | |---------|-------------| | status | Runtime status overview | | doctor | System diagnostics | | providers | List available providers | | routes | Provider routing configuration | | circuit-log | Provider circuit breaker state | | health | Provider health checks | | chat | Send a message in a session | | prompt | One-shot prompt | | sessions | List all sessions | | session-show | Show session transcript | | session-add | Create a new session | | session-export | Export sessions to file | | tools | List available tools (67) | | tool | Execute a specific tool | | agent | Run agent orchestration | | workflow | Execute workflow step | | repl | Interactive REPL mode | | serve | Start HTTP server | | desktop | Launch desktop app | | --json | JSON output mode |

Tools (67 built-in)

File operations, code search, shell execution, agent actions, multi-agent coordination (team-create / team-list / team-delete / team-status / agent-message / subagent-spawn / subagent-list / subagent-status), persistent todos (todo-add / todo-list / todo-done), task lifecycle (task-submit / task-list / task-get), memory v2 (memory-save / memory-read / memory-list / memory-search / memory-delete), worktree controls (worktree-enter / worktree-exit), web (web-search / web-browse / fetch-readable / html-to-markdown / http-get / http-post / json-query), notebook (notebook-edit), LSP hover (lsp-hover), git (git-status / git-diff / git-log / git-commit / git-branch), and more. All file tools enforce workspace-root path security via runtime/file_guard.rs.

# Read a file
cargo run -p octocode-cli -- tool read-file src/main.rs

# Search codebase
cargo run -p octocode-cli -- tool search "TODO"

# List files
cargo run -p octocode-cli -- tool list-files src/

Development

# Run all tests (336+ unit, 0 failed at last release gate)
cargo test --workspace --no-fail-fast

# Run clippy (0 warnings policy)
cargo clippy --workspace -- -D warnings

# Run E2E tests (requires running server)
cargo test --workspace -- --ignored

Project Structure

octocode/
├── crates/
│   ├── octocode-core/       # Domain types, contracts, error types
│   ├── octocode-api/        # Provider registry, HTTP client, streaming
│   ├── octocode-mcp/        # MCP discovery and transport
│   ├── octocode-skills/     # Skill trait and framework
│   ├── octocode-plugins/    # Plugin system
│   ├── octocode-runtime/    # Session, tools, permissions, workflows
│   ├── octocode-commands/   # CLI command parsing (27 commands)
│   └── octocode-cli/        # Entry point: CLI, server, desktop
├── ui-shell/                # Canvas-rendered WebUI workbench
├── config/                  # Auto-created runtime config
├── scripts/                 # Build, deploy, test scripts
└── docs/                    # Planning and documentation

Principles

1. Keep feature parity work explicit and testable.
2. Separate stable runtime contracts from UI shells and integrations.
3. Treat Windows and macOS as first-class platforms.
4. Prefer mature implementations and constrained refactoring over speculative rewrites.

Current executable surface

The current repository already provides a locally runnable baseline:

1. octocode-cli status
2. octocode-cli doctor
3. octocode-cli providers
4. octocode-cli commands
5. octocode-cli sessions
6. octocode-cli session-show
7. octocode-cli session-add
8. octocode-cli chat
9. octocode-cli session-export
10. octocode-cli tools
11. octocode-cli tool read-file
12. octocode-cli tool write-file "path|content"
13. octocode-cli workflow
14. octocode-cli agent
15. octocode-cli repl "status|health|providers|tools|workspace|commands|doctor|circuit-log|sessions"
16. octocode-cli circuit-log
17. octocode-cli routes
18. octocode-cli snapshot
19. octocode-cli events
20. octocode-cli ui-export ui-shell/data/app-state.json
21. octocode-cli --json for machine-readable output
22. octocode-cli serve for the local backend workbench server
23. octocode-cli desktop for the embedded Wry desktop shell

Local deployment

Current local deployment and bootstrap documentation lives in:

1. docs/deployment.md
2. docs/current-implementation-status.md
3. docs/composer-ime-evaluation.md
4. docs/desktop-distribution.md
5. scripts/start-local.ps1
6. scripts/start-local.sh
7. scripts/start-webui.ps1
8. scripts/start-webui.sh
9. scripts/package-desktop.ps1
10. scripts/package-desktop.sh
11. scripts/package-windows-installer.ps1
12. scripts/package-macos-installer.sh
13. scripts/package-linux-installer.sh
14. scripts/test-regression.ps1

Current scope note

This repository is still in the staged refactor phase. It now includes a real OpenAI-compatible provider client, provider health checks with automatic local/remote/stub fallback, file-backed runtime workflow, local config writeback, a canvas-rendered workbench shell, and a Wry-based embedded desktop surface. The full Claw Code / Claude Code feature surface, MCP parity, plugin parity, and provider breadth are not complete yet. The current goal is to keep the runtime core, provider path, canvas workbench, and desktop shell verifiable while the richer integrations are built incrementally.

UI shell notes

The current ui-shell follows these interface constraints:

1. A traditional macOS-style top menu bar and window chrome
2. A VS Code-like left activity rail and explorer sidebar
3. A centered conversation/editor surface
4. A right-top workspace and settings pane
5. A right-bottom integrated terminal area
6. Direct local backend calls for chat, tool execution, settings writeback, and command palette actions
7. Canvas-rendered sidebar, message list, command preview, workspace summary, tool runner shell, settings summary list, terminal viewer, and composer shell
8. Native text inputs remain only as the input layer for composer/settings/tool controls until IME-safe textarea replacement is validated
9. Menu labels and placeholders can be translated through built-in locale files under ui-shell/locales/ or a runtime locale plugin override
10. The View > Language menu ships with four built-in locales: English, Japanese, Korean, and Chinese
11. The terminal, provider, settings summary, tool shell, and composer summary surfaces now consume the unified runtime snapshot plus /api/events feed rather than reconstructing provider/runtime state inside the UI shell
12. The composer now routes slash-commands such as /snapshot, /events, /read, /list, /tool, /plan, /search, and /reload into the same runtime snapshot/event surface used by the CLI and HTTP APIs
13. The composer also supports simple multi-step slash pipelines like /read README.md | list ., which are normalized into a structured pipe command response with per-step timing
14. The terminal pane now exposes events, state, and workflow views, all derived from the same unified snapshot plus event feed surface

To preview the current shell:

1. cargo run -p octocode-cli -- chat demo "hello octocode"
2. cargo run -p octocode-cli -- serve 999 demo
3. or ./scripts/start-webui.ps1 -Port 999 -SessionId demo
4. or cargo run -p octocode-cli -- desktop 999 demo
5. For browser-based verification only, open http://127.0.0.1:999/ui-shell/
6. To emit a runnable desktop bundle directory, run ./scripts/package-desktop.ps1 on Windows or ./scripts/package-desktop.sh on Unix-like systems
7. To emit a Windows installer EXE, run ./scripts/package-windows-installer.ps1
8. To prepare the macOS installer path on a macOS host, run ./scripts/package-macos-installer.sh
9. To prepare the Linux installer tarball path on a Linux host, run ./scripts/package-linux-installer.sh
10. The generated Windows installer supports silent installation with Octocode--windows-x64-setup.exe /Q:A
11. The default Windows install target is %LOCALAPPDATA%\Programs\Octocode\
12. To run the full HTTP/WebUI regression suite against a live server, run `powershell -ExecutionPolicy

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sievepub-2000
• Source: sievepub-2000/octocode
• License: Apache-2.0
• Homepage: https://github.com/sievepub-2000/octocode

Install and usage instructions live in the source repository linked above.