# Octocode

> Multi-agent open-source programming and task-execution toolkit. Rust workspace with a permission-aware runtime, pluggable provider routing (OpenAI, Gemini, DeepSeek, Qwen, Kimi, GLM, Ollama, OpenAI-compatible gateways), built-in tool catalog (shell/web/files/skills/memory), session persistence, /metrics, and a zero-build WebUI + wry desktop shell.

- **Type:** MCP server
- **Install:** `agentstack add mcp-sievepub-2000-octocode`
- **Verified:** Pending review
- **Seller:** [sievepub-2000](https://agentstack.voostack.com/s/sievepub-2000)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [sievepub-2000](https://github.com/sievepub-2000)
- **Source:** https://github.com/sievepub-2000/octocode
- **Website:** https://github.com/sievepub-2000/octocode

## Install

```sh
agentstack add mcp-sievepub-2000-octocode
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`](https://rustup.rs)
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+):**

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

**macOS / Linux (bash / zsh):**

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

**Direct (any platform with cargo already installed):**

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

After installation:

```bash
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)

```bash
# 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:

```ini
# 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`.

```bash
# 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

```bash
# 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](https://github.com/sievepub-2000)
- **Source:** [sievepub-2000/octocode](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sievepub-2000-octocode
- Seller: https://agentstack.voostack.com/s/sievepub-2000
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.