# ipsupport-code [![ci](https://github.com/ipsupport-llc/ipsupport-code/actions/workflows/ci.yml/badge.svg)](https://github.com/ipsupport-llc/ipsupport-code/actions/workflows/ci.yml) [![release](https://img.shields.io/github/v/release/ipsupport-llc/ipsupport-code?sort=semver)](https://github.com/ipsupport-llc/ipsupport-code/releases) [![license](https://img.shields.io/github/license/ipsupport-llc/ipsupport-code)](LICENSE) [![go](https://img.shields.io/github/go-mod/go-version/ipsupport-llc/ipsupport-code)](go.mod) [![ipsupport-code — analyze, fix, test, report](https://raw.githubusercontent.com/ipsupport-llc/ipsupport-code/main/docs/hero.webp)](https://ipsupport-llc.github.io/ipsupport-code/) **Website: [ipsupport-llc.github.io/ipsupport-code](https://ipsupport-llc.github.io/ipsupport-code/)** A small, lightweight **self-learning coding agent** for your own model — any OpenAI-compatible server, local or cloud — in a single static binary, with a **built-in risk model** that stops a dangerous tool call for you. It drives that model through a reason → act → observe loop over a handful of fat tools (`file`, `run`, `git`, `web`, `calc`), recovers from tool errors using lessons it learned on past runs, and — after each task — reflects and writes new lessons to disk so it actually gets better over time. Local by default, but the same loop runs **any OpenAI-compatible provider** (OpenAI, Anthropic, Grok, Groq, OpenRouter, Z.ai) — switch in one command — and it can **delegate a task to a sub-agent on a different model**, so a local agent can hand a review to a frontier one and compare. See [Providers](#providers--local-or-external) and [Sub-agents](#sub-agents). The interactive UI is a Claude-Code-style **TUI** (Bubble Tea): live-streamed tool calls and observations, markdown answers, syntax-highlighted diffs, a **plan / auto** mode toggle, non-stealing approval prompts, and a status bar showing the model, context usage, and tokens. Piped/non-interactive runs fall back to a plain line REPL. It will not match a frontier model. It's built for **micro-tasks** on your own machine, with your own model, under a permission policy you control. > Not affiliated with Anthropic's Claude Code; the name reflects a similar > terminal-agent UX. **At a glance** - 🧰 Fat tools — `file` · `run` · `git` · `web` · `calc`, behind a permission policy + workspace jail - 🧠 Self-learning — distils lessons from each run and recovers from repeat mistakes - 🎯 Goals — `/goal` pursues a multi-turn objective; a judge re-feeds it until it's actually met - 🌐 Any model — local first ([LLMTray](https://github.com/ipsupport-llc/llmtray) on a Mac, LM Studio, Ollama, vLLM — keyless local servers included), or any OpenAI-compatible provider - 🤝 Sub-agents — delegate/fan-out across other models **or local CLI agents** (codex/claude/…) and merge the results - 🛎️ Steer live — `/steer ` nudges a running task mid-flight (and `/btw ` asks a quick side question), without stopping it (esc still cancels) - 🛡️ Built-in risk guardrail — a local model inside the binary scores every tool call; a flagged one stops for you even when the policy allows it, and it learns from your y/n ([Risk check](#risk-check)) - 🪶 Lightweight — a ~2.7 KB system prompt and a ~5 KB tool catalog, about 2,000 tokens before your task; one ~20 MB binary, no runtime - 🔒 Read-only runs — `-read-only` answers a review or a question with nothing allowed to change - 💰 Guardrails — `/budget` spend cap per run · `/diff` to review what the agent changed - 🧩 Plan/auto modes · ⏪ `/rewind` · 🔌 MCP · 📦 skills · ♻️ self-updating **New here?** Install below, then jump to [Quick start](#quick-start). ## Install **One-liner** (macOS/Linux) — auto-detects your platform, verifies the SHA-256, installs to `~/.local/bin`, and prints how to run it (and how to add it to PATH if needed): ```sh curl -fsSL https://raw.githubusercontent.com/ipsupport-llc/ipsupport-code/main/scripts/install.sh | sh ``` That installs the latest **nightly**; append `-s -- latest` for the newest stable release, `-s -- v0.22.0` for a specific tag, or a second arg for a custom path. **Windows** (PowerShell) — installs to `%LOCALAPPDATA%\Programs\ipsupport-code`, verifies the SHA-256, and adds it to your user PATH: ```powershell iex (irm https://ipsupport-llc.github.io/ipsupport-code/install.ps1) ``` That's the nightly; for a channel/tag use the scriptblock form (so it can take an arg): `& ([scriptblock]::Create((irm https://ipsupport-llc.github.io/ipsupport-code/install.ps1))) latest`. Both installers also add the short name **`ipco`** beside it (a symlink; on Windows a one-line `ipco.cmd`), unless something else already owns that name. **Homebrew** (macOS/Linux) — the latest stable release, with `ipco` beside it: ```sh brew install ipsupport-llc/tap/ipco ``` Homebrew then owns the install: `update` points you at `brew upgrade ipsupport-code` instead of replacing the binary. **Or download the archive** for your platform from the [latest release](https://github.com/ipsupport-llc/ipsupport-code/releases/latest) (or the rolling [`nightly`](https://github.com/ipsupport-llc/ipsupport-code/releases/tag/nightly)): `darwin-arm64` (Apple Silicon), `darwin-amd64` (Intel Mac), `linux-amd64`, `linux-arm64`, `windows-amd64`, `windows-arm64`. Each release also ships `checksums.txt` (SHA-256). ```sh tar -xzf ipsupport-code_*_darwin-arm64.tar.gz # .zip on Windows chmod +x ipsupport-code # macOS may quarantine a downloaded binary: xattr -d com.apple.quarantine ./ipsupport-code ./ipsupport-code -version ``` **Or build from source** (pure Go, `CGO_ENABLED=0`, cross-compiles from any host): ```sh make build # host binary at dist/ipsupport-code make release # every target into dist/ go install github.com/ipsupport-llc/ipsupport-code/cmd/agent@latest # installs as `agent` ``` ## Providers — local or external The agent and tools are model-agnostic, so you can point them at any OpenAI-compatible API and switch in one command — run a strong cloud model for a hard task, then drop back to your local one: ``` /ai pick a provider from a list (built-ins: openai, anthropic, grok, groq, openrouter, zai) /ai key openai sk-… add an API key for a built-in provider (one command) /ai add mylab https://api.lab.co/v1 llama-3.1 key=sk-… add a CUSTOM provider + key in one step /ai openai switch to it · /ai local back to your local server /model pick from the server's models (↑↓, type to filter) · /model gpt-4o switch directly ``` Pasting a key on Linux? A middle-click paste is swallowed by the mouse-wheel scroll tracking — use **Ctrl+Shift+V** (bracketed paste), which always works. **Add a provider by hand.** Any OpenAI-compatible endpoint works as a first-class provider straight from the config — no command needed, and **no API key required** for a keyless local server (Ollama, vLLM, a second LM Studio). Add it under `providers` and point `provider` at it: ```json { "provider": "ollama", "providers": { "ollama": { "base_url": "http://localhost:11434/v1", "model": "qwen2.5-coder:7b" } } } ``` It's then active at launch and switchable via `/ai ollama` and `/config`. Switching keeps your session, tokens, and mode. Keys live in `~/.config/ipsupport-code/config.json` (written `chmod 600`) or fall back to the env var (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `OPENROUTER_API_KEY`, `ZAI_API_KEY`). For an endpoint that only issues short-lived keys, give the provider a command that prints one instead of a key: ```json { "provider": "gateway", "providers": { "gateway": { "base_url": "https://llm.example.internal/v1", "model": "some-model", "api_key_cmd": ["get-key"], "api_key_ttl": 3000 } } } ``` The command runs on first use, and its trimmed stdout is the key. The key is kept in memory and never saved. It runs again once `api_key_ttl` seconds have passed (0 or unset means no timed refresh), and once when the server answers 401, after which the request is retried one time. It gets up to 5 minutes, so it can open a browser for a sign-in. What it writes to stderr is shown as it writes it (a URL or code to act on), and a failure shows that output. It has no terminal input. It runs without a shell, so a PowerShell helper is `["powershell", "-NoProfile", "-File", "get-key.ps1"]`. Background checks (the context-window probe) never start it. When it is set it wins over `api_key` and the env var. Like the rest of the connection it is machine-level: a workspace's `.agent/config.json` can't set it. `/config` opens an interactive settings panel: **↑↓** to move, **Enter** to change the selected row, **esc** to close — changes apply and save as you make them, no hand-editing JSON. - **Connection** edits the provider in use, the local server included: the **provider** and **model** are picked from a list (↑↓ to scroll, type to filter; a model the server doesn't list can be typed), its **address** (host, port, path), **API key** (typed masked; empty keeps it, `ctrl+d` removes it), server **type** (LM Studio or plain OpenAI-compatible) and **context window** (any size; 0 = auto-detect). A built-in provider's address can point at a proxy or your own gateway; empty puts it back. - **Providers** adds or edits an OpenAI-compatible endpoint, and removes one picked from the saved ones (confirmed with a second Enter; the one in use falls back to local). - Tuning values — temperature, top_p, output cap, idle timeout, retries, and the goal judge's output cap — are typed; the rest cycle in place. Values are edited like a shell line: ←/→, home/end, ctrl+u. - While a task runs, reasoning (also `/reasoning `), temperature, top_p, the output caps, retries and loop detection take effect from the model's next reply and are saved when the task ends; other changes are staged until then. - A setting this project's `.agent/config.json` also sets is marked: that file wins at the next start. ## Sub-agents Define a **profile** — a named model — and the agent gains an `agent` tool: it can **delegate a self-contained task to a sub-agent on that model** and use the answer. A second opinion, another model's strength, or the same code reviewed across 2–3 models at once. Run your main loop on a local model, then have it fan a review out to a couple of frontier models and merge the findings. A profile is the only way to delegate (and so the curated list of what the assistant may spawn). Build one interactively — provider → model list → name — from `/config`, or on the command line: ```text /agents add grok openrouter x-ai/grok-4.3 # omit the model to list them /agents add architect openai gpt-4o /agents # list profiles /agents rm grok # remove one ``` Then just ask — e.g. *"review internal/tool across grok and architect, then merge."* The assistant calls `agent(profile, task, dir)`: `dir` (optional, `~` expanded) points a sub-agent at **another project** — it gets its own jail there, so it can work on `~/other-repo` without leaving the rest of your disk exposed. A pure fan-out of several profiles **runs in parallel**, each on its own live status line; the main model then merges the results into one answer. Safety: every spawn **asks for approval** (even local ones cost compute) until you relax it with `/permissions agents on`. Sub-agents read/write files and use git but **only run shell commands if you enable it** with `/agents exec on`. They inherit the current mode, can't spawn their own sub-agents (depth 1), and their tokens are recorded in `/usage` like any other. ### External CLI agents Locally installed CLI coding agents (Codex, Claude Code, Muse, aider…) can be sub-agents too — registered as **external profiles**: ```text /agents add-tool # scan PATH: which known CLI agents are installed /agents add-tool codex # one word — codex/claude/gemini/qwen/aider/goose/opencode/muse /agents add-tool mytool mytool --headless {task} # any other tool ({task} = where the task goes) ``` The assistant delegates through the same `agent` tool; the CLI runs in the target `dir`, and the assistant gets back the **tail of its output plus a `git diff --stat` summary** (review the full patch with `/diff`). Use the CLI's **non-interactive mode** (`exec` / `-p` / `--message`) — an interactive launch just hangs until the timeout (15 min default, `timeout` per profile in config.json). Muse (Meta's Muse Code) runs as `muse exec {task}` and keeps its own approval and sandbox on in that mode; to launch it with other flags, use the full form (`/agents add-tool muse muse exec {task}`). ⚠ External agents run **outside the sandbox**: their own tools, their own permissions, no policy jail, and `/rewind` can't see their edits. That's why every launch asks its **own approval** (`external CLI agents` category) — even when ordinary spawns are set to allow; `a` on the prompt relaxes it for the session. ### Background jobs (fire-and-forget) Any sub-agent — LLM or external CLI — can run as a **detached background job**: the assistant adds `background=true`, the call returns at once, and it keeps working while the job runs. When the job finishes you see a `✓ job #N` notice, and the **result is folded into the assistant's next step** — even mid-task, via the same between-steps seam as [`/steer`](#steering-a-running-task-steer-and-asking-on-the-side-btw), so a job that lands while the assistant is working doesn't wait for the next task to be noticed. `/jobs` lists them (each running one shows `⚙ running ` plus `↳ ( ago)` for an external agent — a long gap hints it's stuck, not working), `/jobs result ` prints one in full, `/jobs kill ` cancels. Jobs survive their parent task (and esc) — perfect for a long codex review running while you continue in the main loop. ### Steering a running task (`/steer`) and asking on the side (`/btw`) `esc` cancels a task. Two lighter touches don't stop it: - **`/steer ` folds a note into the running task** — it lands on the very next step to redirect the work ("`/steer the loader is in internal/config, not cmd`"), without waiting for the task to finish or queuing as a follow-up. The note stays pinned above the input until it lands, then the log says so: `↪ steer delivered (step 7): …`. One typed while the model writes its final answer still reaches this task — it goes on with your note instead of finishing. If the task ends before the note lands (esc, a stop), the note comes back into the input rather than opening your next task. While a [goal](#goals) stands, a delivered note amends it: the judge checks the work against your corrections too, and they survive a `/goal go` after a restart. Typed while idle, `/steer` steers the next task you start. - **`/btw ` asks a quick side question** while the task keeps going — it's answered in **one turn, no tools**, from the live conversation, then work resumes ("`/btw what test framework is this repo using?`"). The answer doesn't steer the task; it's just for you. ### Prompt templates (`/snip`) Save a prompt you reuse and pull it back when you need it. `/snip save ` stores your **last prompt** under a name (or `/snip save ` to store text directly); `/snip ` drops that template **into the input box** so you can tweak it and hit Enter — not auto-sent. `/snip list` shows them, `/snip rm ` deletes. Templates are stored globally (`~/.config/ipsupport-code/snippets.json`), so they follow you across projects, and Tab completes both the subcommands and your snippet names. ## Updating The binary updates itself in place from GitHub Releases: ```sh ipsupport-code update # update on the current channel ipsupport-code update nightly # switch to the nightly channel (saved) and update ipsupport-code update stable # switch back to stable ``` `/update` does the same from inside the REPL. On startup it does a quick, best-effort check and prints a one-line notice if a newer build is out on your channel (`stable` by default — set `"channel": "nightly"` in `~/.config/ipsupport-code/config.json`, or switch with `update nightly`). Local dev builds are never nagged. To silence the startup check on a pinned or package-managed install without going fully offline, set `ipsupport-code config set update_check false`. **Working directory.** Launched from a parent dir (or `~`)? `/cd ` points the session at your project — relative file/run/git paths resolve there, and sub-agents inherit it as their default `dir`, so you set the path once instead of repeating it. It stays inside the workspace jail. **Offline?** `/offline on` cuts the agent's OWN internet use — the web tool refuses with a clear "no internet" message and the startup update check is skipped. Your configured model connection is untouched either way — if it's a local server on localhost it needs no network anyway; if you pointed it at a remote endpoint, that traffic still goes out. `/offline off` re-enables it. ## Usage statistics and rating **Anonymous usage statistics** help decide what to work on. They are **on by default for a new install** — first-run setup says so — and **an update never turns them on** for an install that existed before: it is written off. - **What is sent**: one report per day, at the first launch after that day ends (nothing runs on a timer). It holds the version, OS and its version, CPU architecture, Apple chip (Apple silicon only), memory size, language, how many times each feature was used (`tasks`, `tool_calls`, `goals`, `subagents`, `external_agents`, `mcp`, `skills`, `plan_mode`, `local_model`, `cloud_model`), the coarse **family** of models used (`qwen`, `nemotron`, `claude`…) and a random install ID. - **Never sent:** code, prompts, commands, tool arguments or output, file names or paths, model names, API keys, provider URLs. - `/telemetry` shows how the last send went (accepted, refused and why, or failed), the days waiting and exactly the reports they will send. `/telemetry off` (or `ipsupport-code config set telemetry false`) turns it off and deletes the install ID and every unsent counter; `/telemetry reset` makes a new ID. - Nothing is recorded under `DO_NOT_TRACK=1` or in `/offline` mode, from a piped first run that never saw setup, or by a development build. A workspace's `.agent/config.json` can't turn it on. - The first report goes only after the first day ends, so it can be turned off before anything leaves the machine. The server's side — what it keeps and for how long — is [ipsupport-api's telemetry spec](https://github.com/ipsupport-llc/ipsupport-api/blob/main/docs/telemetry.md). **Rate it** from inside the agent: `/rate 5 works great with my local model` (add `--name ` to sign it). Ratings are moderated, then shown on the [website](https://ipsupport-llc.github.io/ipsupport-code/#reviews). After the first day a single dim line may suggest it — at most once every two weeks; `/rate never` stops that. ## Quick start 1. Start a local server with a **tool-calling** model loaded (e.g. `qwen2.5-7b-instruct`). On a Mac we recommend [LLMTray](https://github.com/ipsupport-llc/llmtray) — a menu-bar app running [mlx-lm](https://github.com/ml-explore/mlx-lm) natively on Apple Silicon; [LM Studio](https://lmstudio.ai), Ollama and vLLM do the same job anywhere. **No local model?** Skip this — the next step asks. 2. First interactive run asks whether you have a local model server running. If yes, it looks for a running LLMTray (`:8765`) or LM Studio (`:1234`) and offers the one it finds as the server URL, then asks for the API key (blank for a local server) and model, and confirms the connection. If no, it asks for a provider name — a built-in (`openai`, `anthropic`, `grok`, `groq`, `openrouter`, `zai`) uses that vendor's real endpoint with just a key; **any other name** is treated as your own OpenAI-compatible endpoint (a self-hosted gateway, LiteLLM, a proxy…) and additionally asks for its Base URL — so a custom endpoint is never silently pinned to the wrong vendor's URL. Either way it saves to `~/.config/ipsupport-code/config.json` (re-run with `-init`). 3. Run a one-shot task, or open the REPL: ```sh ./ipsupport-code "use calc to compute (1234*9)+sqrt(2)" ./ipsupport-code # interactive TUI ./ipsupport-code -C ~/proj "summarize what main.go does" ``` **Which session?** Memory is saved per **workspace** (the `-C` dir, default the current one) and per **agent name** (default `ipsupport-code`). A one-shot or piped run silently **continues** the saved thread; the interactive TUI opens a **navigable chooser** (↑↓ to pick a saved session, **enter** to open, **d** to delete, **esc** for the newest) when any exist. To start clean or pick a thread from the CLI: Flags go **before** the task text — anything after it is part of the task, not a flag, and the agent says so rather than quietly sending it to the model: ``` $ ipsupport-code "do the thing" -override provider=openai error: -override provider=openai must come BEFORE the task text — written there it was read as part of the task, not as a flag ``` To point a single run at a different provider or model without touching `config.json` (the provider must already be configured): ```sh ./ipsupport-code -override provider=openai "task" # this run only ./ipsupport-code -override provider=openai \ -override providers.openai.model=gpt-5 "task" # …and its model ``` ```sh ./ipsupport-code -new "fresh task" # ignore the saved session ./ipsupport-code -session review "look at X" # start a named thread ./ipsupport-code -session review -resume # continue it ./ipsupport-code -session review -new # start it over (overwrites) ``` A **named** session is an explicit choice, so relaunching one without saying which you meant is an error rather than a silent guess: ``` $ ./ipsupport-code -session review error: session "review" already exists — -resume to continue it, or -new to start over (overwrites it) ``` **Read-only runs** — for a review, or a question about the code, with nothing allowed to change: ```sh ./ipsupport-code -read-only "review the diff against main" ``` File writes, git changes and MCP servers are refused. Commands run without asking, inside the OS sandbox (Landlock on Linux 6.7 or later, Seatbelt on macOS, whatever `sandbox` is set to) with the workspace read-only like the rest of the disk: only temp dirs and the user cache dir are writable, and there is no network. The git tool's own git runs there too, since a status or diff runs the filters the repository's config names. Where there is no such sandbox, or the workspace or its repository sits in a temp or cache dir, commands and the git tool are refused too, and the run says why. The session is neither restored nor saved, and nothing is learned from it — not even from an approval answer; a run whose own files (trace, usage, skills, lessons, settings) would land in the workspace or its repository doesn't start. A repository nested inside the workspace with its git dir kept elsewhere is not looked for. On Linux a command can still change a file's mode and times (Landlock doesn't cover them), never its contents. Each named session keeps its own saved thread, its own **standing goal** and its own input history, so two of them can work the same checkout at once — a local model in one terminal, a cloud model in another — without stealing each other's goal. Learned **facts and lessons stay shared**: those describe the project, and both sessions benefit from what either one learns. Logs are per **workspace** and per session: ``` ~/.config/ipsupport-code/agent-test.log # -C test ~/.config/ipsupport-code/agent-test-remote.log # -C test-remote ~/.config/ipsupport-code/agent-test-cloud.log # -C test -session cloud ``` Named by the directory's basename, so you can tail one without looking up a hash. (Two checkouts with the same basename share a log — unlike the state directory, where a collision would mix two projects' memory rather than two logs.) Every shared state file is written under a cross-process lock, and the ones both runs add to — learned facts, lessons, the usage ledger, input history — are **merged** under it rather than overwritten, so a second run never erases what the first learned. In the TUI, `/sessions` lists/switches/deletes threads, `/new ` starts a fresh named thread (the old one stays in `/sessions`), and `/new` clears the active one. ## Modes: auto, plan, manual Cycle with **shift+tab** (auto → plan → manual), or use `/auto`, `/plan` and `/manual`. The current mode shows at the bottom of the screen. The mode lasts for the session only. - **auto** (default) — the agent executes the task with tools, under your permission policy. - **plan** — read-only: it investigates and proposes a numbered plan, and every state-changing tool call is **blocked at the engine**, so it can't touch anything until you accept. - **manual** — the agent executes, but **asks before every change**: every shell command, every file write, append, edit and mkdir, mutating git, sub-agent spawns and MCP. It asks even where `/permissions` or an allow rule would let the call through. Reads and searches stay free. An **`a`** at a prompt still covers its kind for the rest of the session. The deny floor holds in every mode. When a plan-mode task finishes with a plan, you get a one-key **handshake**: **enter** to accept — switches to auto and immediately executes the plan — **m** to execute it in manual instead, asking before each change, or **esc** to keep planning (stay in plan mode; type to refine). A switch to manual that the model took while still writing the plan simply carries on in manual. If the switch came too late for that, the handshake shows and **enter** runs the plan in manual. Switching the mode **mid-task** takes effect at the start of the model's next turn, never in the middle of one. The log says from which step (`⇄ manual mode on — from step 3`), and a switch into or out of plan mode is said to the model too. If the task ends before the model takes another turn, the switch applies to the next task. A sub-agent already running keeps the plan or auto mode it started with, while manual applies to it at once. ## Permissions Mutating actions ask for approval by default. The prompt goes **modal**: **`y`** approves, **`n`** denies, **`a`** allows the whole session (see below), **↑/↓** toggle the explicit Yes/No, and every other key is ignored outright — nothing leaks half-typed into the chat while it's waiting. **esc** drops back to typing (to steer or queue something else first); the approval stays pending either way, and answering it always lands you back where you were. A non-overridable deny floor (`rm -rf`, `sudo`, secrets, `.git`, `.env`, …) is always enforced. **No answer is a no.** A prompt waits two minutes, with the countdown in the status line. Then the call is denied and the task goes on without it, instead of sitting on the prompt until you come back. Only an explicit yes runs anything. The model is told that nobody answered, not that you said no. It goes on without the call and says at the end that the call is still waiting on you. The risk model learns nothing from a prompt that ran out, because nobody judged that call. **Grant it for the session.** Press **`a`** on any prompt to stop asking about that whole *kind* of action (file changes, shell, git, sub-agent spawns, MCP) for the rest of the session — in memory only, never written to config, cleared by `/new` and `/clear`. It's the "yes, and don't ask again for now" you reach for mid-task without loosening anything permanently. For a permanent relaxation instead, `/permissions files on` auto-allows non-destructive file ops in the workspace (the deny floor still applies); same for `/permissions run on`. That choice **is** saved to the workspace config. **OS sandbox (opt-in).** The permission engine decides *whether* a command runs; an OS-level sandbox can additionally confine *what it can touch* once it does — so even an allowed command can't write outside the workspace. Turn it on with `config set sandbox auto` (picks the platform's mechanism: **Seatbelt** on macOS, **Landlock** on Linux — kernel 5.13+), or name one explicitly (`seatbelt` / `landlock`). Shell (`run`) commands then execute inside the kernel sandbox: writes are confined to the workspace (plus temp dirs and the user cache, so build tools keep working), the network follows `/offline` (Landlock needs kernel 6.7+ for that part), reads and everything else are unchanged. It's **off by default**, and on a platform/kernel without a supported sandbox commands run unconfined as before. External CLI agents are **not** sandboxed (they run outside it, as documented above). ## Risk check A small local classifier scores every tool call for how dangerous it looks. A call it flags — or one it could not read in full — **stops for you even where the permission policy would have run it without asking**: an allow glob, a `run.default` of `allow`, an earlier `a` on a prompt. Your answer is the override: `y` runs it, `n` refuses it (the model is told), and `a` stops asking about that kind of call for the rest of the session, flagged ones included. An `a` given at an ordinary prompt covers only the unflagged ones. An external agent's or an MCP server's launch command comes from config, not from the call the model made — a checkout's own file can set it — so it is scored too, as it starts. Turn the asking off with the **risk check** row in `/config` (saved as `risk_check`), or for one run with `-skip-risk-check`. `-skip-permissions` turns it off too: nothing is asked at all. A project's own `.agent/config.json` can turn it on but not off — it is what stops a flagged command in a checkout whose file allows everything. On or off, the scorer logs what it thought next to what the policy did: ``` msg="risk shadow" tool=run action=shell risk=1.00 top=credential_access labels="credential_access=1.00 sandbox_escape=1.00" policy=allow disagreement=allowed-but-flagged call="run shell command=cat ~/.ssh/id_rsa" msg="risk shadow: scored 1 call(s), 1 over 0.50, 1 disagreed with the policy" ``` You see it where it matters, not only in the log. A call the scorer is unhappy about carries its suspicion on its own line, and again at the approval prompt — which is the moment it is worth anything, since your answer there is the label it learns from: ``` ⚙ run shell cat ~/.ssh/id_rsa ⚠ possible credential access (0.98) ⚠ approve run: cat ~/.ssh/id_rsa ⚠ possible credential access (0.98) y approve · n deny · a allow all shell commands this session, flagged ones too · ↑ Yes/No · or keep typing · no answer in 2m is a no ``` Nothing is shown for a call it had nothing to say about — a number on every routine line is how a risk signal gets tuned out. The `disagreement` column is the whole product. **allowed-but-flagged** is what the check stops; **gated-but-unremarkable** is what the policy asks about that the scorer would not have. Tail them with `IPS_LOG=debug`, and turn scoring off entirely with `IPS_RISK=off`. It is a hashed-feature linear model — `sigmoid(Wx+b)` over word and character n-grams, six labels (`destructive`, `sandbox_escape`, `credential_access`, `network`, `external_side_effect`, `safe`). Inference is pure Go with no dependency of any kind: 768KB of `float32` embedded in the binary, ~28µs per call. Training is offline and separate (`scripts/train_risk.py`, stdlib only); its only output is the weights file. **A shell line is scored by its parts.** Read as one text, a long harmless tail diluted a destructive head: `rm -rf quotesdemo && cat > REPORT.md <<'EOF' …` came out at 0.07. The line is now cut by the rules of the shell it runs in — `sh` off Windows, PowerShell (or `cmd` when `run.shell` says so) on it (`internal/shellsplit`) — and its code (commands and operators, without heredoc bodies, here-strings or comments, which are data) each group of commands joined by `|` `&&` `||` (a pipeline's danger can be in the joining: `curl … | sh`) and each command in it are scored; the call's risk is the highest. A heredoc that is expanded or fed to a shell or an interpreter (`sh </risk-feedback.jsonl ``` Rows written before v0.61, which recorded an approval as `["safe"]`, are skipped the same way. Two runs of the trainer on the committed dataset produce a byte-identical `model.bin`, so the shipped model is reproducible from the files in this repo. **What it is not.** It does not replace the permission policy or the sandbox. The policy is still better at the extremes — it denies `rm -rf /` outright, whatever the allow-list says. And learning needs the prompt: with `-skip-permissions` nobody is asked, so nothing is answered and nothing is learned. ## Skills On-demand instruction packs — the user-extensible version of guides-on-demand. Only an **enabled** skill adds a single line to the system prompt; the model loads a skill's full instructions on demand, so the base prompt stays lean no matter how many you install. Eight curated skills ship in the binary (`test-first`, `debug-systematically`, `git-flow`, `research-first`, `minimal-code`, `review` — multi-model review via sub-agents — `subagents`, how to delegate and fan work out, and `plan`, a `.agent/plan.md` checklist so multi-step work resumes itself), seeded **disabled** so you opt in. Built-in skills refresh on upgrade unless you've edited them. ``` /skills list installed skills (on/off) /skills on git-flow enable one /skills install add a .md by URL, or every skill in a git repo /skills remove ``` ## MCP servers Connect [Model Context Protocol](https://modelcontextprotocol.io) servers and the agent gains their tools — but through **one** proxy tool, not by dumping every server's schema into the prompt (which would swamp a small model's context). Add them to `~/.config/ipsupport-code/config.json`: ```jsonc "mcp_servers": { "fs": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/some/dir"] }, "gh": { "command": "github-mcp-server", "env": { "GITHUB_TOKEN": "…" } }, "remote": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer …" } } } ``` Two transports: **stdio** (a local subprocess via `command`) and **HTTP** (a remote `url`, with `headers` for auth — e.g. `Authorization: Bearer`). `/mcp` lists the servers and their tools. The model uses the `mcp` tool — `list` to discover, `schema` to see a tool's inputs, `call` to run one. Servers connect lazily on first use; **every `mcp call` asks for approval** (it's external code). Sub-agents don't get MCP. ## When a local model misbehaves Small/“thinking” local models can loop in their own reasoning or over-think. The levers, in order: - **`/reasoning low`** (or `minimal`/`off`) — trims the model's reasoning. There's no universal API for this, so it's **per-model** and stored in its provider's own shape (`reasoning_effort` for OpenAI, `reasoning:{effort}` for OpenRouter, `chat_template_kwargs:{enable_thinking}` for Qwen/LM Studio). `/reasoning low` on the current model writes the right shape for known providers; for others set it raw in `config.json` under `reasoning` (keyed by `` or `/`). - **A runaway turn is auto-stopped.** A single turn generating far past the context window (looping) aborts with a clear message instead of streaming for minutes. Press **esc** to cancel anything sooner. - **`/reflect off`** — skip the post-task learning pass if it's where a weak model loops (the status shows *“task done — distilling lessons”* so you can tell the task itself already finished). Or **`/reflect `** to run learning on a stronger model, and **`/reasoning reflect low`** to give the learning pass its own (leaner) reasoning setting. - **`/skills on plan`** — for long multi-step work, the model keeps a checklist so it resumes instead of drifting. - **Fine-tune it on the tool schema.** If a specific local model keeps garbling the `{"action":...,"params":...}` shape (the registry recovers several common ones automatically, but not all), see [FINETUNING.md](FINETUNING.md) for a from-scratch guide, including where to mine real training examples you already have on disk. ## Rewind `/rewind` opens a list of the session's steps — pick one (↑↓, enter) to roll back to **before** it ran: every file that step (or its sub-agents) changed is restored to its prior content, files it created are removed, and the conversation is trimmed back. Checkpoints are taken at the start of each turn, so you can rewind no matter how a turn ended (finished, esc, a loop, an error). Shell commands, git, and network calls **can't** be undone — only files and the chat. (REPL: `/rewind` lists, `/rewind ` applies.) Snapshots live for the session. ## Goals A **goal** is a multi-turn objective — not a single turn. `/goal ` sets one and starts pursuing it: the agent works, and when it thinks it's finished a **judge** (a separate model call) decides whether the goal is *actually* met. If it isn't, the goal is **re-fed** to the agent — kept in focus, with the gap the judge named — and it keeps going. This repeats up to a **TTL** (`/goal ttl `, default 6 re-feeds) before it gives up, on top of the usual esc / stuck / runaway guards and a hard step cap. The goal is a first-class, persisted object: it lives in the workspace's state directory (`goal.json`), so it survives a restart — an unfinished one offers to resume **once** on the next start (not every time), and a completed goal clears itself. `/goal` shows the standing goal and its status; `/goal go` resumes it; `/goal clear` drops it; `/goal off` disables the loop (a goal then runs as a single pass). Plain tasks (anything you type that isn't a goal) run as one pass with no judge overhead — only an explicit goal gets the loop. The judge defaults to done on any unparseable reply, so a confused model can't trap the agent in the loop. The whole thing is gated on real progress: a turn that calls no tools is never judged or re-fed. If a re-fed model then finishes without doing any work, it gets **one** push to act before the loop gives up (turn it off with `config set goal_nudge false`). And when the loop stops without the judge ever confirming success, it says so plainly — *"goal not confirmed complete, `/goal go` to keep pushing"* — instead of implying it's done. When the judge confirms the goal, the agent says how long the work took: *"✓ goal met — worked 1h12m over 3 runs"*. That counts the working time of every run at the goal, across `/goal go` resumes and restarts, and leaves out time spent waiting on an approval prompt. ## Context & auto-compact The status bar shows `ctx 4.1k/8k` — the size of the last prompt vs. the model's context window. The window is **auto-detected** from LM Studio's `/api/v0/models`; set `llm.context_window` to override (0 disables auto-compact). If the configured model isn't loaded, the window of the model that is loaded is used until it is, and the agent says so. It also warns once when the model id isn't in LM Studio's list, and when a reply comes from a different model than the one configured — some servers answer an id they can't resolve with whatever model is loaded, without an error. When the prompt passes ~75% of the window the session is **auto-compacted** into a short summary to free room (run it any time with `/compact`; the threshold and whether it summarizes at all are configurable — see `memory`/`compact_threshold` below). Every task's goal and outcome is also archived in full, never summarized, to `sessions/.archive.jsonl` in the workspace's state directory — once there's something in it, the model gets a `history` tool to recall or search past tasks that a compaction summary has since shortened. ## REPL commands Anything not starting with `/` is run as a task. Tab completes commands. | command | what | |---|---| | `/plan`, `/auto`, `/manual` | plan mode (propose only), auto mode (execute) or manual mode (execute, ask before every change) — also shift+tab | | `/goal ` | set & pursue a multi-turn goal (judge re-feeds until met); `go` · `clear` · `ttl ` · `off` | | `/skills` | list / toggle / install on-demand instruction packs | | `/permissions` | relax approval for non-destructive file/shell actions | | `/status` | config, knowledge base, and trace paths | | `/budget [usd]` | cap estimated spend per run — refuses new tasks once hit; `off` disables | | `/diff` | show uncommitted workspace changes (what the agent changed), colorized | | `/steer ` | fold a note into a **running** task without stopping it — lands on its next step, and the log shows when (esc cancels instead) | | `/btw ` | ask a quick side question mid-task — one-turn answer, **no tools**, the task keeps going | | `/snip [name]` | prompt templates — `/snip ` pulls a saved template into the input to edit & send; `save [text]` (omit text → your last prompt) · `list` · `rm ` | | `/usage` | token spend + **estimated $** (today / 7d / 30d / all, by day, by model); `clear` · `purge ` · `retain ` | | `/login` | (re)configure server URL / model / key, then reload | | `/new [name]` | start a NEW session (the old one stays in `/sessions`) | | `/clear` | wipe this session's context + the screen (same session) | | `/compact` | summarize the session so far to free up context | | `/color [name]` | change the TUI frame color (cycles if no name) | | `/rename ` | rename the agent (saved in settings) | | `/sessions` | pick a saved session to switch to (`/sessions ` switches, `/sessions delete ` deletes) | | `/agents` | sub-agent profiles: `add` (LLM) / `add-tool` (external CLI) / `rm` / `exec` | | `/telemetry` | anonymous usage statistics: exactly what is sent · `on` · `off` · `reset` | | `/rate` | rate ipsupport-code: `/rate <1-5> [--name ]` · `later` · `never` | | `/loop [xN] ` | re-run a task on an interval (e.g. `/loop 5m `, `/loop 30s x10 `); **esc** stops it | | `/help` | command list | | `/exit`, `/quit` | leave | The input is multi-line: paste a whole block (e.g. a YAML snippet) and it keeps its line breaks, the box grows and word-wraps instead of scrolling on one line, and **alt+enter** (or **ctrl+j**) inserts a newline by hand. **Enter** submits. **History.** With an empty input, **↑ / ↓** recall previous messages to re-run or fix a typo — the first **↑** jumps to your last prompt. History is **persisted per workspace** (`history` in its state directory), so recall spans past runs; `/history` lists recent prompts and `/history ` filters them, and **ctrl+r** opens an incremental reverse-search (type to narrow · ctrl+r older · enter use). **Tab** completes `/commands` and `@file` paths against the workspace. (PgUp/PgDn and the wheel scroll the log.) Everything you type is a **message queue**. While a task runs the input stays live: Enter **queues** the next message — a task *or* a `/command` — pinned above the input and drained in order when the task finishes (deferred commands are no longer dropped). **↑** on an empty input pulls the last queued message back to edit or drop, and **esc** cancels. **Approvals.** When the agent asks to approve a file write or shell command, it takes over the keys: press **y** (approve), **n** (deny) or **a** — allow every action of that kind (file/shell/git/spawn/external) for the rest of the session; `/permissions` shows what you allowed and `/permissions reset` revokes it. **↑/↓** toggle the explicit Yes/No prompt; **esc** backs out to keep typing (queue a message first) without answering — the approval just keeps waiting. **Shell.** `/shell` (or `!`) drops you into an interactive shell in the workspace — do things by hand, exit to return. `!cmd` runs a single command and shows its output. These are your commands, not the agent's, so they aren't gated by the permission policy. **Custom system prompt.** The built-in engine prompt is deliberately tiny; you can replace it with `.agent/system.md` (per project) or `~/.config/ipsupport-code/system.md` (global). `ipsupport-code -dump-prompt` prints the default to start from (`> .agent/system.md`). Your `CLAUDE.md`, environment, and skills are still appended after it. `/status` shows which prompt is in effect. (A bloated prompt makes a small model call tools worse — edit at your own risk.) ## How it works - **Native tool calling.** Talks to any OpenAI-compatible server — LLMTray, LM Studio, Ollama, vLLM, a LiteLLM proxy or a cloud provider — and lets the model call tools natively. One client for all of them; `llm.base_url` / `llm.api_key` or a `providers` entry picks the endpoint. - **Fat tools.** One tool per domain, each `{"action": ..., "params": {...}}`. The catalog stays tiny (~1k tokens) so small models prefill fast and route well; a declarative `Domain` generates each tool's schema, help, and validation. - **Proactive help.** When a tool fails, a matching lesson from past runs is injected straight into the error the model sees — it doesn't have to ask. - **Reflection.** After a task, a second model pass distills durable lessons into `~/.config/ipsupport-code/knowledge.json` (env-general tool pitfalls) and durable **facts** about the current project (build/test/run commands, where things live, conventions) into `facts.json` in the workspace's state directory — folded into the prompt next run. Each lesson tracks when it was last seen (bumped on recurrence); `/knowledge` reports the store and `clear` / `purge ` / `retain ` prune stale ones (`retain` auto-purges on startup) so the memory doesn't accrete junk forever. - **Code search.** The `file` tool's `search` action greps the workspace by regex (`file:line: match`), skipping VCS/dep/build dirs and binaries — no external `grep`. - **Session memory.** Remembers your goals and its answers across turns and across restarts, kept per workspace **and per agent name** (`sessions/.json` in the workspace's state directory). On startup the TUI shows a **navigable chooser** of saved sessions (↑↓ / enter / d) — and on restore it replays the recent exchanges so you pick up where you left off. `/new ` starts a fresh named thread; `/new` wipes the active one. - **Cache-friendly prompts.** A local server reuses its prompt cache only while each request starts with exactly what the last one did, so within a session the prompt only grows at the end. The system prompt stays as the session began: facts learned after a task, and the plan-mode directive, arrive as an `` on the next task's message instead of rewriting it. On a local provider the goal judge and the reflection pass go out as the next message of the task itself — same prompt, same tools — so they are answered from the cache instead of prefilling the whole record again (they fall back to their own prompt when that yields no answer). - **State outside the project.** What the agent writes for itself — goal, facts, lessons, prompt history, sessions — lives in `~/.config/ipsupport-code/state/-/`, never in the workspace, so a model listing the project can't find and replay its own state. Files *you* write (`.agent/config.json`, `system.md`, `judge.md`, `compact.md`, `instructions.md`) stay in the project. Older installs are moved out of `.agent/` once, on first start. - **Resilience.** Exponential-backoff retry on transient 5xx/network errors, an idle watchdog that aborts a silently-stalled stream, and a stuck-loop guard. - **Project instructions.** Reads a `CLAUDE.md` / `AGENTS.md` / `.agent/instructions.md` from the workspace into the system prompt. - **Trace = dataset.** Every step (goal, tool call, observation, final, lesson) is appended as JSONL to `~/.config/ipsupport-code/traces.jsonl`. - **Usage ledger.** Token spend is recorded per day and per provider/model to `~/.config/ipsupport-code/usage.json` and accumulates across runs; `/usage` shows today / 7-day / 30-day / all-time rollups, with `clear`, `purge `, and a `retain ` retention window. ## Configuration Settings merge over safe defaults from two JSON files: - **`~/.config/ipsupport-code/config.json`** — machine-level: the `llm` connection (server URL, model, key, `context_window`). Written by first-run setup. - **`/.agent/config.json`** — per-project: the permission policy (see [`.agent/config.example.json`](.agent/config.example.json)). Wins over the user file for everything EXCEPT the `llm` connection and `providers` — a workspace is a checkout you might not fully trust, so it can tighten or loosen what the agent may do, but it can't redirect your model endpoint or add a provider preset while your real API key still gets sent wherever it points. Edit either file from a script with the `config` subcommand — no interactive session needed: ```sh ipsupport-code config set update_check false # any key, dotted paths for nested ipsupport-code config set goal_max_returns 8 # JSON values keep their type ipsupport-code config get llm.model # print the effective value ipsupport-code config unset channel # back to the default ipsupport-code config list # effective config, one key per line ipsupport-code config --local set run.default allow # write the workspace file ``` Values that parse as JSON keep their type (`false`, `8`, `["x"]`); anything else is a literal string. `set` writes the global user file by default (`--local` targets `/.agent/config.json`); a wrong type or a misspelled key is rejected rather than saved. `get`/`list` show the effective, merged value — a key sitting at its zero default (e.g. `offline` when off) prints nothing, like `git config --get`. The workspace file always wins over the global one — e.g. the interactive `/config` panel's file/run permission rows persist to the *workspace* file (they're a per-project concern), so setting the same key globally afterward has no visible effect; `set`/`unset` warn on stderr when that's about to bite you. `run.timeout_seconds` caps how long a shell command may run (default 60s); raise it for slow builds/test suites, or let the model pass a larger per-call `timeout`. On Windows, `run.shell` picks the shell commands run in: unset uses `pwsh` if installed, else Windows PowerShell; or set `pwsh`, `powershell` or `cmd` (`ipsupport-code config set run.shell cmd`). Elsewhere it is always `sh`. Cross-task memory: once the context window fills past `compact_threshold` (default `0.75`), the session is folded into an LLM-written recap to free headroom — `memory raw` turns that off entirely, keeping turns verbatim and only dropping the oldest ones outright (no paraphrase) once there are too many (500 messages — high enough that it's a rare backstop, not routine): `ipsupport-code config set memory raw` / `config set compact_threshold 0.85`, or toggle/cycle both live from the `/config` panel. Either kind of cut — an LLM recap or the plain drop — changes the front of the prompt, which breaks a local server's KV-cache reuse for it (matched only on an identical prefix) just as much as the other; `raw`'s high cap exists so that cost stays rare instead of hitting on every turn once a session runs long. Permissions for `run` and `file` resolve per action: a **deny** glob blocks, an **allow** glob runs without asking, otherwise the **default** (`ask`/`allow`/`deny`) applies. Run-command deny globs match *anywhere* in the command (so `rm -rf*` catches `cd x && rm -rf /`); file globs are path-aware (`**`, `*.go`) and confined to `jail`. A run **allow** glob must match each chained command whole, and `*` means any characters: `ls*` also allows `lsof -i`. To allow just `ls` with arguments, write `ls *` (plus `ls` for the bare command). The protective deny floor is always unioned in — your config adds to it, it can't remove it. It judges the words the shell will actually run — after quotes and backslashes are removed, through `command`/`exec`/`env`/`xargs` and similar wrappers, across `;`, `&&`, `||`, `|` and `&` — and the deny and secret-file floors ignore case, since macOS and Windows file systems do. It is still a static check: `sh -c "…"`, variables and encoded commands get past it, and the `ask` default is what stops those. Logging: `IPS_LOG=debug|info|warn|error` (default `warn`). In the TUI it writes to `~/.config/ipsupport-code/agent.log` (so raw log lines don't bleed over the screen) — `tail -f` it to watch retries/warnings live; a piped/one-shot run logs to stderr. ## Layout ``` cmd/agent CLI, plain REPL, the Bubble Tea TUI, external CLI-agent runner internal/llm OpenAI-compatible client (streaming, retry, context detection) internal/agent the reason → act → observe loop (+ plan mode, goal judge) internal/tool fat tools: file, run, git, web, calc, agent, mcp, skill, help, history internal/skill downloadable, toggleable instruction packs internal/policy workspace permission engine (+ jail, deny floor) internal/knowledge persistent pitfall store internal/reflect post-task lesson + project-fact distillation internal/trace JSONL decision trace (the dataset) internal/config config load/merge internal/mcp MCP client (stdio + HTTP) internal/usage token/cost ledger (powers /usage and /budget) internal/selfupdate checksum-verified in-place self-update internal/risk risk scorer behind the risk check (pure-Go inference, embedded weights) internal/sandbox opt-in OS sandbox for `run` (Seatbelt on macOS, Landlock on Linux) internal/procgroup kill a command's whole process tree on cancel/timeout internal/filelock cross-process lock for files shared between running sessions internal/e2e end-to-end tests: real loop, tools and policy against a fake server internal/textutil · internal/atomicfile shared helpers (clipping, atomic writes) ``` ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). CI runs gofmt, `go vet`, the race suite, and a cross-compile of every target on each push and PR. [BACKLOG.md](BACKLOG.md) lists work that is designed but not built — each entry says what is wrong, what the fix is, and what that fix would break. [adr/](adr/README.md) records the architecture decisions the code rests on — where state lives, what a workspace may override, why external agents are gated separately, how the risk model is trained and shipped. ## License [MIT](LICENSE) © ipsupport-llc The binary carries the licenses of everything it links (all MIT or BSD) and of the data its risk model was trained from: `/license` lists them, `ipsupport-code --license` prints the full texts. After changing dependencies, regenerate them with `go run ./internal/legal/gen`; a test fails until you do.