<div align="center">
# woca
**A single-binary coding-agent harness — web UI first, plus TUI and CLI — built on an explicit agent graph.**
[](https://github.com/ProjAnvil/WoCA/actions/workflows/ci.yml)
[](https://go.dev/)
[](LICENSE)
[Features](#features) · [Install](#installation) · [Quickstart](#quickstart) · [Architecture](#architecture) · [Extending](#extending-woca) · [HTTP API](#http-api)
**English** | [简体中文](README.zh-CN.md)
</div>
---
woca is a harness for coding agents, written in Go. It drives any
Anthropic-compatible or OpenAI-compatible model through an explicit,
inspectable **agent graph** — model → tools → model — with a
human-in-the-loop permission gate, token-level streaming, auto-compaction,
subagents, skills, hooks, MCP servers, and an embedded web UI, all shipped as
**one static binary** with no runtime dependencies.
The agent loop is not a hidden `while` loop buried in a framework callback.
It is a graph you can read: nodes, conditional edges, reducers, checkpoints,
and interrupt/resume, powered by the langgraph runtime from
[langchain-golang](https://github.com/ProjAnvil/langchain-golang) and
composed in [`internal/agent`](internal/agent). Every run is streamed
token-by-token, every tool call passes a deterministic permission gate, and
every conversation is persisted as a resumable transcript.
## Contents
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quickstart](#quickstart)
- [Web UI (recommended)](#web-ui-recommended)
- [Interactive TUI / REPL](#interactive-tui--repl)
- [One-shot](#one-shot)
- [Providers & models](#providers--models)
- [Permissions](#permissions)
- [Architecture](#architecture)
- [Editions & repository layout](#editions--repository-layout)
- [The bridge (private-cloud form)](#the-bridge-private-cloud-form)
- [Configuration](#configuration)
- [Sessions, memory & undo](#sessions-memory--undo)
- [Multi-agent](#multi-agent)
- [Subagents](#subagents)
- [Agent teams](#agent-teams)
- [Extending woca](#extending-woca)
- [Skills](#skills)
- [Custom subagents](#custom-subagents)
- [Hooks](#hooks)
- [MCP servers](#mcp-servers)
- [Marketplace plugins](#marketplace-plugins)
- [Capability plugins](#capability-plugins)
- [Reuse your existing setup](#reuse-your-existing-setup)
- [Slash commands](#slash-commands)
- [HTTP API](#http-api)
- [Observability](#observability)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
## Features
**Agent runtime**
- **Explicit agent graph** with conditional edges, an `add_messages`
reducer, checkpoints, and interrupt/resume — runs paused on an approval
resume across process restarts; calls interrupted by a crash are marked
interrupted (result unknown) and never re-run.
- **Token-level streaming** of text and tool-call deltas through the graph;
the TUI and web UI render output live while tools execute.
- **Streaming tool execution**: read-only calls are dispatched while the
model is still streaming; permission-gated calls always wait for the
deterministic gate so interrupts stay exact.
- **Resilient model I/O**: retry with exponential backoff and an optional
fallback model on both invoke and stream paths; truncated responses
(`max_tokens`) are escalated and continued automatically; oversized
prompts trigger reactive compaction with a single-retry guard; each tool
round is held under an aggregate size budget with deterministic
placeholder replacement.
- **Auto-compaction** with a CJK-aware token estimator: old tool results are
snipped and large ones micro-compacted before the head is summarized; a
circuit breaker disables it after repeated failures (`/compact` resets).
- **Mid-turn steering** (Codex parity): submit a message while a run is in
flight in the TUI or web UI and it is queued into the live run immediately
instead of waiting for the turn to finish; interrupting a run with a
pending steer resubmits it as a fresh turn right away instead of losing it.
- **Background loop closure**: `Bash run_in_background` shells, background
`Task` subagents, and session cron (`ScheduleCron`) queue tagged
notifications that ride the next run; when the session is idle they start
a run on their own (`auto-wake`), with the chain capped by
`auto-wake-limit` so a notification loop cannot run forever.
- **Thinking / reasoning support**: reasoning effort levels and streamed
reasoning content, rendered as collapsible blocks in the web UI.
**Tools & safety**
- **20+ built-in tools**: `Bash`, `BashOutput`/`BashInput`/`KillShell`
(background shells: poll output — `wait_ms` blocks until the shell
finishes — write stdin; a shell's output keeps the newest 1 MiB, and when
older bytes were dropped `BashOutput` starts with an
`[N older bytes truncated]` marker), `Read`, `Write`, `Edit`, `NotebookEdit`,
`Glob`, `Grep`, `ListDir`, `TodoWrite`, `WebFetch`, `WebSearch`,
`AskUserQuestion`, `EnterPlanMode`/`ExitPlanMode`, `Task`/`TaskOutput`/
`TaskStop`, `TaskCreate`/`TaskGet`/`TaskUpdate`/`TaskList`, `Skill`,
`SendMessage`, plus LSP-backed code intelligence.
- **Permission gate** with four modes, explicit allow/deny/ask rules
(exact names, regexes, `Tool(glob)` matchers), and an input-sensitive
read-only classifier — `git status` auto-allows, `rm -rf` never does.
- **File-level undo**: every `Write`/`Edit` snapshot is kept per session;
`/undo` / `/redo` revert and re-apply changes, repeatable.
**Surfaces**
- **Embedded web UI** (the recommended surface): sessions grouped by
workspace, streaming assistant bubbles with tool cards, file sidebar with
syntax-highlighted previews, image uploads and screenshot paste, settings
panel — served from the same binary over SSE and managed as a background
daemon via `woca web start | stop | restart | status`.
- **Interactive TUI** (bubbletea): live streaming, approval prompts,
vim-mode input, themes, scrollable transcript.
- **One-shot CLI** for scripting and pipes.
**Ecosystem**
- **Skills** (`SKILL.md` + YAML frontmatter), **custom subagents**
(`.woca/agents/*.md`), **hooks** (13 event groups, matchers, exit-code
semantics), **MCP** client (stdio + streamable HTTP, tools, resources,
prompts, notifications, OAuth), and **capability plugins** (managed
browser automation, PDF tooling, and Office document support) — see
[Extending woca](#extending-woca).
- **Layered configuration**: flags > workspace `.woca/` > user `~/.woca/`
for skills, agents, MCP servers, and instruction files.
- **Persisted settings** in SQLite (default) or PostgreSQL, with API keys
and DSNs **encrypted at rest** (AES-256-GCM).
- **Usage & quota**: per-session token accounting with estimated cost, and
remaining-quota display for subscription plans (GLM Coding Plan,
Anthropic/OpenAI OAuth logins, DeepSeek balance).
## Requirements
- macOS or Linux (x86-64 / arm64)
- Go ≥ 1.26 to build from source
- A model provider: an Anthropic-compatible or OpenAI-compatible API key,
a gateway, or an OAuth login
## Installation
**From source (recommended for now):**
```bash
git clone https://github.com/projanvil/woca.git
cd woca
make # build web frontend + binary into build/woca
```
**With `go install`:**
```bash
go install github.com/projanvil/woca/cmd/woca@latest
```
The web UI is embedded at compile time via `go:embed`, and `web/dist` is a
build artifact (not tracked in git). A bare `go build` / `go install`
still compiles, but the binary serves a placeholder page ("woca web UI not
built") until you run `make web` (or plain `make`) once to build the
frontend — run it again whenever you change anything under `web/`.
**Make targets:**
| Target | Description |
|--------|-------------|
| `make` / `make serve` | build frontend + binary; `serve` also launches the web UI |
| `make build` | build the binary to `build/woca` |
| `make test` / `make race` | unit tests (optionally with the race detector) |
| `make lint` | golangci-lint |
| `make install` | install to `/usr/local/bin` |
## Quickstart
Point woca at a provider (persisted, encrypted at rest):
```console
$ woca config set provider glm
$ woca config set glm-api-key <key>
```
or export `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` and skip configuration
entirely.
### Web UI (recommended)
The web UI is the primary way to use woca. Manage it as a background
daemon:
```bash
woca web start # launch the web UI in the background → http://127.0.0.1:3484
woca web status # check whether it is running
woca web restart # restart the background web UI
woca web stop # stop it
```
The server embeds the frontend and exposes the agent over an SSE API —
create sessions, start runs, watch streaming events, resolve permission
prompts, browse workspace files, and manage settings.
Other ways to run it: `woca serve` keeps the server in the foreground
(`--addr`, `--no-browser`), and from an interactive session `/web` starts
it on demand (`/web <port>`, `/web off`, `/web status`).
### Interactive TUI / REPL
```bash
woca # bubbletea TUI on a terminal; line REPL otherwise
woca --resume last # continue your most recent session
```
Answer approval prompts with `y`/`n` and scroll with `pgup`/`pgdown`. To
interrupt a running turn, press `esc` twice (`esc-esc`) or `ctrl+c` in the
TUI, or cancel it from the web UI (`POST /api/runs/{id}/cancel`). In the
line REPL, a line starting with `!` runs a shell command and feeds its
output into the conversation. See [Slash commands](#slash-commands).
**File context:** type `@` (at the start of a line or after a space) to
complete and attach a workspace-relative file or directory; the referenced
content is expanded into the model's message while the transcript still
shows your original `@path` text.
**Steering:** typing while a turn runs and pressing `enter` sends it into the
live run immediately instead of waiting for the turn to finish (Codex
parity); the footer shows "steering (N): ...". Interrupting (`esc-esc` or
`ctrl+c`) with a pending steer resubmits it as a fresh turn right away
instead of losing it.
**Composer:** `ctrl+j` inserts a newline without submitting; `ctrl+g` opens
the current draft in `$VISUAL` (falling back to `$EDITOR`) and replaces the
draft with the saved file's contents on return. `shift+tab` cycles the
permission mode (default → acceptEdits → plan → readOnly →
bypassPermissions), matching the web composer. Both ctrl+j/ctrl+g are
remappable — see `/keybindings`.
**Keybindings:** `/keybindings` shows the effective composer, session, and
vim-mode bindings; `/keybindings open` creates (or reports the path of)
`~/.woca/keybindings.json`, a flat `{"key": "action"}` override file for the
composer actions (`composer:newline`, `composer:editor`).
### One-shot
```bash
woca -p "explain this repo's build system"
woca -p "fix the failing test" --dangerously-skip-permissions # use with care
```
## Providers & models
| Provider | API | Default model | Notes |
|----------|-----|---------------|-------|
| `anthropic` (default) | Anthropic Messages | `claude-sonnet-4-5` | or OAuth login: `woca login` |
| `openai` | OpenAI Chat Completions | `gpt-4o` | any compatible `--base-url` gateway |
| `glm` | GLM (Anthropic-compatible endpoint) | `glm-4.6` | GLM Coding Plan quota display supported |
| `deepseek` | DeepSeek (Anthropic-compatible endpoint) | `deepseek-chat` | balance display supported |
Any OpenAI-compatible gateway works via `--base-url`
(`OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` or the persisted setting). Model
fallback (`--fallback-model`), thinking levels (`/thinking`), and per-model
reasoning-effort mapping are wired through the same router.
## Permissions
| Mode | Read-only / meta / web | File edits | Shell |
|------|------------------------|------------|-------|
| `default` | allowed | ask | ask |
| `acceptEdits` | allowed | allowed | ask |
| `bypassPermissions` | allowed | allowed | allowed |
| `readOnly` / `plan` | allowed | denied | denied |
Read-only classification is **input-sensitive**: `Bash("git status")`
auto-allows while `Bash("rm -rf …")` asks. Explicit rules override the mode:
```json
{
"permissions": {
"allow": ["Bash(git *)", "Read"],
"deny": ["Bash(rm *)"],
"ask": ["FileWrite(secrets/**)"]
}
}
```
Precedence is `deny` → `ask` → `allow` → mode default. Subagents are
fail-closed: an un-granted write permission surfaces as *permission denied*
instead of prompting.
File tools also take **path rules**: `Write`/`Edit`/`NotebookEdit`/
`Read`/`Glob`/`Grep`/`ListDir` match their path argument against a
path-shaped glob (`*` and `?` stay inside a segment, `**` spans
directories), and the virtual names `FileWrite(...)`/`FileRead(...)` cover
the write/read operation classes — `"deny": ["FileWrite(**/.env)"]` blocks
every write to any `.env`, `"ask": ["FileWrite(secrets/**)"]` re-asks for
writes under `secrets/` even in `acceptEdits` mode. Search results
additionally never follow a symlink that resolves outside the searched
directory.
**Same-origin by design.** The HTTP API serves no CORS headers: the web UI
is served by the same origin that owns the API, and remote or cross-origin
clients connect through the edge/bridge tunnels rather than direct browser
calls.
## Architecture
```
cmd/woca cobra CLI: flags, config, REPL, one-shot, serve
# agent core
internal/agent the coding-agent graph (langchain-golang/langgraph
runtime): gate, plan mode, streaming execution,
recovery, compaction, teams, goals
internal/agentbuild composition root shared by every entry point that
runs the agent
internal/runner streaming run loop + interrupt handling + rendering
internal/tools tool set + registry + permission categories
internal/permissions permission modes, rules, read-only classifier
internal/model provider router: retry, fallback, invocation
internal/compact auto-compaction / summarization
internal/tokens CJK-aware token estimator
internal/prompt system-prompt assembly
internal/promptref @path prompt-reference expansion
internal/contextx runtime context (git status, etc.) for the prompt
internal/diffutil small unified diffs for the web UI's Changes view
internal/cost session cost estimation
internal/quota provider quota/usage display
# surfaces
internal/tui bubbletea terminal UI
internal/repl line-REPL input parsing and editing
internal/console slash commands shared by TUI, REPL, and web
internal/slashcmds builtin slash-command table (shared without an
import cycle)
internal/keybindings user-overridable TUI action map
internal/servefront server-role frontends: serve (web UI server) and
web (background daemon)
internal/webd web-GUI background daemon (pidfile, start/stop)
internal/webgui on-demand web UI service (the /web command)
internal/webfx web framework: gin/fiber-shaped API on net/http
internal/sdkout machine-readable headless output (json /
stream-json)
# web & API plumbing
internal/server web server: sessions, runs, SSE, settings API
internal/gateway L1 edge middlewares shared by every deployment
internal/websearch WebSearch backends: provider registry, failover,
cooldown, throttling (configured from Settings)
internal/searchapi generic JSON web-search API client (--search-api)
internal/fsb workspace folder browser (jailed, os.OpenRoot)
# storage & state
internal/session JSONL transcript persistence
internal/settings settings database + encrypted secrets
internal/wocadb settings database opener (sqlite / postgres)
internal/store namespace+key JSON document store
internal/memory ladyM memory-engine adapter
internal/runstate externalized run ledger (runs + event streams)
internal/runws run-scoped workspace carrier
internal/merge layered configuration merge
# platform & operations
internal/bus in-process message bus (SendMessage)
internal/obslog harness observability log (size-rotated JSONL)
internal/settingswatch management-plane write propagation to roles
internal/tracing observability core (span vocabulary + sink interface)
internal/logging zerolog wrapper
internal/notify terminal notifications
internal/oauth OAuth 2.0 device-authorization-grant client
internal/config user-facing configuration
internal/claudeenv ~/.claude skills/MCP import
internal/cpserde checkpoint payload serialization
internal/platform/ shared platform primitives (authn, authz, httpx,
machineid, …)
internal/skills SKILL.md loader (layered: flag > workspace > user)
internal/agents subagent definitions (.woca/agents/*.md)
internal/hooks hook runner (13 event groups)
internal/mcp MCP client (stdio + streamable HTTP, OAuth)
internal/plugins marketplace plugins (skills/agents bundles)
internal/pluginrt capability-plugin runtimes (browser, pdf, office)
```
### Editions & repository layout
woca ships as **two editions** built from one repository:
- **Personal edition** — the `woca` binary: CLI/TUI/REPL plus the local
`woca serve` web UI, zero external dependencies (sqlite, in-process
everything). This is what individual users install.
- **Enterprise edition** — the server roles assembled from the same core
plus the enterprise tree: multi-tenant auth (API keys, native-client
DPoP sessions), queue dispatch with the NATS message plane, the
standalone config service, observability (OTel/Prometheus/Grafana), and
registry DSN discovery. Seven role binaries, none with interactive
surfaces:
- `woca-scheduler` — the modular-monolith API surface: business API plus
the console management authority; no pages of its own
- `woca-worker` — claims runs from the shared runstate ledger and
executes them through the agent (probe port `:9092` by default)
- `woca-config` — the standalone settings management plane; the sole
configuration write surface, plus its own console SPA
- `woca-tenant` — tenant/user/API-key administration CLI (plus the
personal→enterprise memory migration tool)
- `woca-bridge` — the private-cloud execution plane for user machines
(organization-credential login; carries no key management itself)
- `woca-edge` — the stateless edge access point; the control plane's
only public component
- `woca-ops` — the tenant ops console (it issues organization
credentials), plus the skill-asset console under `/skillsvc/`
The registry-coupled roles (`woca-scheduler`, `woca-worker`, `woca-config`,
`woca-edge`) are **fail-closed** on the nacos registry: they require
`WOCA_NACOS_URL` and refuse to start without it, so a minimal
enterprise deployment includes a nacos registry (dev-grade standalone
manifest in `deploy/k8s/00-nacos.yaml`; end-to-end proof in
`deploy/vm/nacos-verify.sh`).
The delivery axis is orthogonal to the edition axis: today both editions
are **self-hosted** (see `deploy/selfhosted/`, `deploy/k8s/`,
`deploy/vm/`); a managed cloud form is a future packaging of the same
enterprise code, not a third edition.
```
internal/ core, shared by both editions (agent, tools, server, fsb, …)
internal/ee/ enterprise-only: msgplane, tenant, configsvc, worker, obs,
discovery, nacosrt, nativeauth, dpop, authcore, consoleauth,
tenantcmd, memcmd, skillsvc (skill-asset API; its console
SPA is skillsvcui on woca-ops), opsconsole/opsui (tenant ops
console API + SPA), bridge (the private-cloud bridge
service), entrygw (the private-core machine registry),
edgegw (the stateless edge access point), edition
(woca-scheduler's composition root)
internal/platform/machineid shared machine identity (enrollment tokens,
Ed25519 identities, opaque access tokens)
web/ shared web UI (personal + enterprise web surface)
ee/ enterprise web consoles (configsvc-web, opsconsole-web,
skillsvc-web)
deploy/selfhosted/ enterprise docker-compose stack (data plane + full)
deploy/k8s/ Kubernetes manifests (server + worker, nacos registry,
observability pipeline)
deploy/vm/ registry fail-closed verification (nacos-verify.sh)
deploy/micro/ per-role distribution packages (binary + start/stop
scripts)
deploy/collector/ OTLP trace bridge into Langfuse / the observability stack
deploy/observability/ OTel Collector + Prometheus + Jaeger + Grafana stack
deploy/terraform/ AWS zone-first deployment of the full stack
cmd/woca personal entry (everything)
cmd/woca-* enterprise role entries (no interactive surfaces)
```
### The bridge (private-cloud form)
`woca-bridge` is the productized private-cloud execution plane: the same
serve surface plus the product identity model — organization credentials
issued by the tenant ops console on the private core (the bridge itself
carries no key management; an unenrolled bridge keeps loopback
trust only), URL+key login with cookie sessions (revocation cascades
from the ops console through the config generation), the
workspace folder browser (`/api/fs/*`, jailed with `os.OpenRoot`), and a
fail-closed bind check (an unauthenticated non-loopback bind refuses to
start). Registered bridges see exactly one control-plane peer — the
stateless edge access point (`cmd/woca-edge`, `internal/ee/edgegw`;
no database, no files, every machine-token check calls home to the
service plane). Behind it the private core splits in two: the registry
routes (`/gw/enroll|renew|heartbeat|resolve|bridges`, mounted on
woca-scheduler's `WOCA_GW_ADDR` listener) and the config pull (`/gw/config`
on woca-config). A one-time enrollment token exchanges for a local
Ed25519 identity plus short-TTL opaque access tokens; pulled settings
install as the managed overlay (locked, `managed_fields` in
`/api/settings`), and a control-plane outage keeps the bridge running
with a STALE flag on the status page. The same outbound channel carries
the NAT-traversal data plane: client traffic parks at the edge until the
bridge's tunnel picks it up and answers against its own handler stack
(SSE streams pass with flushes intact), so any-place web commands a
NAT-hidden bridge with zero inbound ports. Loopback bridges keep the
zero-login personal experience; the personal `woca` binary links none of
this.
The full private-cloud stage ships with it: TLS direct termination
(`WOCA_TLS_CERT/KEY`), the long-poll config channel (push semantics over
pull), worker-led enrollment (fingerprint approval — no token pasting),
the bridge's read-only operations view (live sessions + audit over HTTP +
SPA; user credentials are organization keys issued by the tenant ops
console — the bridge itself carries no key management), a global
health lamp and Markdown diagnostics export, QR pairing on the login
page, and the native client's embedded bridge (bundled binary, zero-login
loopback profile, org-key login with TOFU pinning and OS-keychain key
storage),
the three-entry connection page (embedded / private cloud via the edge
with target-bridge selection / direct bridge — one profile mechanism
underneath), the bridge-local cloud-access settings (`edge.*` keys in the
settings database, SPKI TOFU pin, env override with source labels, page
at Settings → Cloud access), and the two dev compose groups (the
microservices twin plus the edge compose group with `public`/`internal`
network layering and the bridge as an independent container — see
`deploy/selfhosted/BRIDGE.md` for the deployment runbook).
The boundary is enforced, not aspirational: the personal binary never links
`internal/ee` (its dependency baseline is pinned in `ci/deps-personal.txt`),
the enterprise tree never links the interactive frontends, and core
packages reach enterprise capabilities only through seams —
`server.MsgPlane`, `server.NativeAuth`, `servefront.Edition`, and
`wocadb.DSNResolver`. `make check-editions` guards all three directions.
> **Layout changes (2026-08-22).** The enterprise packages moved under
> `internal/ee/` (import paths changed accordingly — e.g.
> `internal/msgplane` → `internal/ee/msgplane`; the enterprise web consoles
> moved to `ee/`); `deploy/enterprise/` is now `deploy/selfhosted/`. The
> personal binary no longer ships the `tenant` and `memory` subcommands
> (use `woca-tenant`), and `woca serve --auth apikey` now requires the
> `woca-scheduler` binary — multi-tenant auth is an enterprise capability.
> **Upgrade note (graph-native HITL).** Sessions paused under the previous
> interrupt-relay topology resume as `interrupted` markers: the affected
> tool calls report "may or may not have run" and never re-execute —
> re-approve by sending a new message.
### The agent graph
```
┌──────────┐ no tool calls ┌──────┐
START ─▶│ model │──────────────────▶│ END │
└────┬─────┘ └──────┘
│ has tool calls
▼
┌──────────┐ ┌────────────┐ asks pending ┌──────┐
│ hooks │──▶ approval ─▶│ tools │────────────────▶│ INT │
└──────────┘ (fan-out) └─────┬──────┘ └──┬───┘
│ (loops back to model) │ resume
└───────────────────────────────┘
```
Gates run in dedicated supersteps so resumes never re-run them: the
`hooks` node evaluates rules/grants/mode and fires Pre/Post tool-use hooks
without interrupting; the `approval` node collects every user ask of the
round (permission, AskUserQuestion, plan approval) into ONE interrupt whose
answer is addressed per call id. Foreground `Task` calls fan out from
`approval` into content-addressed subagent subgraphs (`types.Send` +
`AddSubgraph`): parallel children pause on their own asks — one pause may
carry several cards, each answered by its checkpoint namespace. State is a
`messages` channel (add_messages reducer) plus a `decisions` channel that
persists the round's gate outcomes, so a resumed run never re-derives
consent. A crashed superstep resumes with `interrupted` markers — the
affected tool calls report "may or may not have run" and never re-execute.
### Goal mode
`/goal <objective>` switches the agent into an autonomous loop expressed as
its own graph on top of the agent graph:
```
START ─▶ assess ─▶ execute ─▶ evaluate ─┬─ active ─▶ assess (next cycle)
└─ terminal ─▶ END
```
Each cycle plans (assess), runs a full nested agent turn (execute), then
**verifies with skepticism** (evaluate) — the agent may *claim* completion,
but only verified evidence completes the goal. Budgets (`--cycles`,
`--tokens`), idle auto-continue, and mid-cycle interrupt/resume apply; goal
state persists per session and survives restarts. Manage the loop with
`/goal status`, `/goal pause|resume`, `/goal budget`, `/goal clear`; the web
UI shows cycle/token meters and per-cycle verdicts live.
## Configuration
Settings live in a database under `~/.woca` — SQLite by default (pure Go,
no cgo), PostgreSQL optional via DSN. Credentials and DSNs are stored
**encrypted at rest** (AES-256-GCM; master key in `~/.woca/secret.key`,
mode `0600`). Three entrances share one database:
```console
$ woca config set provider openai
$ woca config set openai-api-key sk-... # stored encrypted
$ woca config list
```
- **Terminal**: `woca config get|set|list`
- **Interactive**: `/settings`, `/memory list|put|get|del`
- **Web UI**: settings panel (`GET`/`PUT /api/settings`)
Key resolution order: `--api-key` flag → `ANTHROPIC_API_KEY` /
`OPENAI_API_KEY` → database (encrypted) → OAuth token. Graph checkpoints
and the memory store each pick a backend (`sqlite`, `postgres`, `file`,
`memory`, `none`).
Behavior settings live in the same store: `auto-wake` (default on) starts a
run when a notification queues for an idle session, and `auto-wake-limit`
(default 20) caps chained auto-wake runs — past the cap notifications stay
queued until the next user run resets the chain (`-1` lifts the cap).
Important flags:
| Flag | Description |
|------|-------------|
| `-p, --prompt` | one-shot prompt (runs non-interactively) |
| `--model` / `--provider` | model name and provider |
| `--base-url` / `--api-key` | provider endpoint and credential |
| `--permission-mode` | `default` \| `acceptEdits` \| `bypassPermissions` \| `readOnly` \| `plan` |
| `--workdir` | working directory (default: cwd) |
| `--mcp` | MCP server as `name=command` or `name=https://…` (repeatable) |
| `--fallback-model` | fallback on exhausted retries |
| `--max-turns` | cap model rounds per turn |
| `--auto-compact` | token-estimate compaction threshold (`0` disables) |
| `--resume` | resume a transcript (or `last`) |
| `--db` | settings database: sqlite path, `postgres://` DSN, or `none` |
| `--checkpoint-dir` | persist graph checkpoints for cross-process resume |
**Pause, crash and upgrade semantics.** Runs paused on an approval resume
across process restarts. A run whose execution superstep was interrupted by
a crash resumes with the affected tool calls marked `interrupted` — the tool
may or may not have run; verify before retrying — and never re-executes
them. Threads paused by relay-era (pre-fan-out) builds resume the same way:
as interrupted markers.
## Sessions, memory & undo
- **Sessions** persist as JSONL transcripts under `~/.woca/sessions`,
grouped by workspace; `/rename` snapshots, `/branch` forks,
`/rewind` jumps to an earlier point, `/export` dumps markdown or
resumable JSON, and `--resume <name|last>` continues anywhere.
- **Memory**: with a memory backend configured, each turn prefetches
memories relevant to your message and attaches them after tool rounds;
`/memory put` writes long-term context that reaches the model later.
- **Instruction files**: `CLAUDE.md` and `AGENTS.md` are injected from the
user level down through every directory from the git root to your
working directory.
- **Undo**: `Write`/`Edit` snapshots are kept per session; `/undo` /
`/redo` revert and re-apply the last change (repeatable). Changes made
by `Bash` or outside woca are not tracked.
### Session activity panel
The web chat header carries a **task list button** (left of the memory
toggle) with a live badge: the brand-colored count is what is running right
now, a red count means something finished with a failure you have not seen
yet. Opening it shows this session's activity in three tabs:
- **Todo** — the model's current todo list with statuses and progress.
- **Background** — background shells and subagent tasks, running items
first; expand a row for its output tail. **Stop** kills the item on the
spot (a confirm notes the consequence). Finished items are capped at the
newest 20 per session; running ones are always kept.
- **Scheduled** — session cron entries with their spec, prompt and next
fire time, plus the auto-wake state (capped / stalled / disabled).
Stop/kill semantics: **stopping an item yourself never wakes the agent** —
the model learns "killed by the user" only with your next message, so you
can prune runaway work without triggering a follow-up run. Items the model
stops or that finish on their own keep the usual auto-wake behavior.
**Deleting a session stops all of its background work** (shells killed,
subagents stopped, cron entries and todos removed).
## Multi-agent
### Subagents
`Task` spawns isolated subagents with their own context window and tool
subset; `TaskOutput`/`TaskStop` manage them. Define custom subagents as
markdown files:
```markdown
<!-- .woca/agents/reviewer.md -->
---
name: reviewer
description: Reviews diffs for correctness and style issues
tools: Read, Grep, Glob
---
You are a critical code reviewer. Report only concrete, actionable issues.
```
The model then calls `Task(subagent_type="reviewer", prompt=…)`.
### Agent teams
For parallel work, teams share a worktree and coordinate through a shared
task list with ownership (`TaskUpdate` claims atomically; `DependsOn`
ordering) and message routing (`SendMessage` pokes idle teammates).
Teammates run autonomous loops with per-teammate timeouts; `/team` shows
membership, tasks, and inboxes.
## Extending woca
### Skills
Drop a `SKILL.md` with YAML frontmatter under `.woca/skills/<name>/`:
```markdown
---
name: commit
description: Write a conventional commit message
---
Write a conventional-commit message for the current diff.
```
The model discovers it and can call `Skill(skill="commit")`. Skills resolve
layered: workspace copies override user-level `~/.woca/skills`.
### Custom subagents
See [Subagents](#subagents). Definitions resolve from `.woca/agents/`
(workspace) over `~/.woca/agents/` (user).
### Hooks
Configure lifecycle hooks in `~/.woca/settings.json` or
`.woca/settings.json`:
```json
{
"hooks": {
"PreToolUse": [
{"matcher": "Bash(git *)", "hooks": [{"type": "command", "command": "echo 'git command incoming'"}]}
],
"PostToolUse": [
{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "cat"}]}
]
}
}
```
Thirteen event groups are supported: `PreToolUse`, `PostToolUse`,
`UserPromptSubmit`, `Stop`, `SessionStart`, `SessionEnd`, `SubagentStart`,
`SubagentStop`, `Notification`, `PreCompact`, `PostCompact`,
`PermissionRequest`, and `PostSampling`. Each hook receives a JSON event on
stdin; stdout is fed back as context. A `PreToolUse` hook exiting `2` denies
the tool; a `PostToolUse` hook exiting `2` blocks continuation.
`SubagentStart`/`SubagentStop` wrap every Task subagent run (payload field
`agent_name`); a `SubagentStop` hook exiting `2` has its stdout appended to
the subagent report as `<subagent-stop-feedback>` (the subagent is not
re-run). `Notification` fires immediately before the permission interrupt
with `permission required: <tool>`.
### MCP servers
```bash
woca --mcp "filesystem=node /path/to/server.js /tmp" \
--mcp "search=https://mcp.example.com/mcp"
```
Tools appear as `mcp__<server>__<tool>`, plus resources
(`mcp__<server>__resources`) and prompts. Both stdio (newline JSON-RPC) and
streamable HTTP (POST + JSON/SSE, `Mcp-Session-Id`) transports are
supported; OAuth-protected servers are authorized once with
`woca mcp auth <name> <endpoint>` (tokens stored encrypted). Server
definitions resolve layered: `--mcp` flag > workspace
`.woca/mcp.json` > user `~/.woca/mcp.json`, and tools added mid-session are
picked up between rounds.
### Marketplace plugins
A plugin is a directory with a `plugin.json` manifest (a Claude-style
`.claude-plugin/plugin.json` layout works too) installed under
`~/.woca/plugins`:
```text
/plugins install ./my-plugin
/plugins install https://github.com/me/my-plugin.git
/plugins install deploy@acme-marketplace
```
The last form resolves `deploy` inside a marketplace — a git URL or local
directory carrying `.claude-plugin/marketplace.json`. `/plugins list`
shows each plugin's contribution counts; `/plugins enable|disable <name>`
toggles a plugin through the `disabled-plugins` settings key (a JSON name
array; disabled plugins contribute nothing and are listed with a
`(disabled)` marker until re-enabled).
Plugins contribute skills (`skills/`), subagents (`agents/`), commands
(`commands/*.md`, exposed as skills named `<plugin>:<command>`), hooks
and MCP servers. Manifest keys accept both spellings:
| Contribution | woca key | Claude key |
|--------------|----------|------------|
| skills directory | `skills_dir` | `skills` |
| agents directory | `agents_dir` | `agents` |
| commands directory | `commands_dir` | `commands` |
| hooks | `hooks` (file path or list) | `hooks` (inline object or `{"source": …}`) |
| MCP servers | `mcp_servers` (file path list) | `mcpServers` (inline object) |
Unsupported keys (`lspServers`, `outputStyles`, …) are ignored and
reported by `/plugins list`. Hook commands and MCP server definitions can
reference the plugin's install directory as `${WOCA_PLUGIN_ROOT}` or
`${CLAUDE_PLUGIN_ROOT}`. Subagents are usable immediately after install;
skills, commands, hooks and MCP servers attach at the next startup.
### Capability plugins
Managed, versioned tool bundles installed on demand into
`~/.woca/plugins`:
- **browser** — hosted browser automation (navigation, clicks, forms,
screenshots) for web testing and research
- **pdf** — a sandboxed Python environment for PDF generation and
processing
- **office** — read and write Office documents (Word `.docx`, Excel
`.xlsx`, PowerPoint `.pptx`) in the same sandboxed Python environment
Browse and install from the settings panel (`/plugins`), which provisions
the pinned runtime and verifies SHA-256 checksums.
### Reuse your existing setup
woca interoperates with common agent conventions: it reads `CLAUDE.md` /
`AGENTS.md` instruction files, discovers skills from `.claude/skills`, and
— from the web settings panel — can import skills and MCP server
definitions from an existing `~/.claude` setup in one click. If you already
run agent tooling, woca picks up your configuration instead of asking you
to rewrite it.
## Slash commands
Available in the TUI, REPL, and web chat input (prefix `/`, with
completion):
| Command | Description |
|---------|-------------|
| `/help` | list available commands |
| `/status` | version, provider/model, permission mode, run stats |
| `/permissions [mode]` | show or set the permission mode |
| `/model [name]` | show or switch the model at runtime |
| `/thinking [level]` | reasoning effort: off \| low \| medium \| high \| tokens |
| `/quota` | remaining quota for subscription plans |
| `/cost` | cumulative token usage and estimated cost |
| `/clear` | start a fresh conversation |
| `/compact` | summarize the conversation to free context |
| `/context` | context-window usage breakdown |
| `/todos`, `/tasks` | todo list / shared task list |
| `/skills`, `/mcp`, `/agents`, `/plugins` | manage extensions |
| `/tools` | list effective agent tools with category and permission safety |
| `/hooks` | list configured hook events, or state that none are set |
| `/undo`, `/redo` | revert / re-apply the last file edit |
| `/rewind`, `/branch`, `/rename`, `/export` | session history navigation |
| `/goal …` | autonomous goal loop (set/status/pause/resume/budget/clear) |
| `/team` | agent team status |
| `/memory …` | inspect and edit the memory store |
| `/settings …` | persisted settings |
| `/init` | generate an `AGENTS.md` project guide |
| `/doctor` | check config, credentials, storage, hooks, permissions |
| `/theme`, `/vim`, `/keybindings` | UI preferences (`/keybindings open` edits overrides) |
| `/web [port\|off\|status]` | embedded web UI control |
| `/output-style` | default \| explanatory \| learning |
## HTTP API
The web server exposes the agent over REST + SSE:
| Endpoint | Description |
|----------|-------------|
| `POST /api/sessions` | create a session (persisted immediately) → `{"session_id":"…","workspace":"…"}` |
| `GET /api/sessions` | list persisted sessions |
| `GET /api/sessions/{id}` | fetch a full transcript |
| `DELETE /api/sessions/{id}` | delete a session (tombstoned against revival) |
| `POST /api/runs` | start a run: `{"session_id":"…","prompt":"…"}` |
| `GET /api/runs/{id}/events` | SSE: `delta` / `reasoning` / `tool_call` / `tool_result` / `goal` / `goal_note` / `interrupt` / `done` / `error` (goal runs stream cycle narration as `goal_note` and end with one unified `delta` reply) |
| `GET /api/events` | global SSE: `session_state` snapshots, plus `wake_capped` when a session's auto-wake chain hits its limit (notifications stay queued) |
| `POST /api/runs/{id}/answer` | resolve an interrupt: `{"approve":true}` or `{"answers":[…]}` |
| `POST /api/runs/{id}/input` | queue mid-turn input |
| `POST /api/runs/{id}/cancel` | cancel a run |
| `GET`/`PUT /api/settings` | read/update persisted settings |
## Observability
Enable the observability log (`--debug-log`, the web settings panel, or
`/debug-log on`) for full harness logging under `~/.woca/logs/`,
size-rotated:
```
logs/woca.log run lifecycle, model usage, summaries
logs/ws-<name>-<hash8>/<session>.jsonl one JSON event per line
logs/ws-<name>-<hash8>/<session>/<run>.json message-level transcript dump
```
Every graph-node dispatch is recorded with phase, duration, and state
summary; in the web UI each assistant bubble gains a debug action that
copies the exact log locations for troubleshooting.
## Development
```bash
make web # build the frontend (required once before go build)
make build # build the binary
make test # unit tests
make race # tests with the race detector
make lint # golangci-lint
```
The frontend is a Vue 3 + TypeScript + Vite SPA under [`web/`](web/README.md);
the demo (`npm run dev:demo`) previews the whole UI with mock data. The
graph runtime, agent loop, permission gate, hooks, compaction, skills, MCP
client, and web server are all covered by unit tests — the project is
built test-first.
See [CONTRIBUTING.md](CONTRIBUTING.md) for code style and PR guidelines.
## Contributing
Issues and pull requests are welcome. For anything larger than a bug fix,
please open an issue first to discuss the design. See
[CONTRIBUTING.md](CONTRIBUTING.md).
## License
woca is released under the [MIT License](LICENSE). It is built on
[langchain-golang](https://github.com/ProjAnvil/langchain-golang),
[bubbletea](https://github.com/charmbracelet/bubbletea), and
[cobra](https://github.com/spf13/cobra).