computah

computah

A self-hosted, terminal-based AI coding agent in Go. It runs against any OpenAI-compatible model server — a local one like LM Studio or Ollama with no key required, or an authenticated cloud/gateway endpoint via an API key. It reads and edits code in a working directory, runs commands with approval, keeps resumable sessions, remembers across them via engram, and extends itself with MCP tool servers.

Install

go install github.com/davasorus/computah@latest

This drops a computah binary on your PATH ($(go env GOPATH)/bin).

Usage

computah                    # start the interactive agent in the current dir
computah run ./project      # ...or in a specific working directory
computah run --resume latest
computah exec "add a health endpoint" --yes    # one-shot, non-interactive
computah eval cases.json --runs 3               # run an eval file
computah dashboard --write                      # web dashboard (two-way)
computah dashboard --headless                   # web-only, no terminal UI
computah config init                            # create ~/.agent/config.json
computah config add-mcp sandbox --command sandbox --arg mcp --prefer
computah version

computah with no subcommand is equivalent to computah run.

AI Usage

• This was created using a combination of Online Claude Code and offline gemma-4-12B

Global flags

An optional API key for authenticated endpoints (cloud OpenAI, a proxied gateway) is read from api_key in the config file or the COMPUTAH_API_KEY env var; it's sent as a Bearer token. Local servers need no key — leave it unset.

Values resolve flag → COMPUTAH_* env → config file → auto-detect.

Configuration

Two layers, both optional:

• CLI surface (url, model) via Viper: a flag, a COMPUTAH_URL / COMPUTAH_MODEL env var, or ~/.agent/computah.yaml.
• Agent behavior (compaction, budgets, MCP servers, hooks, etc.) via the agent's own ~/.agent/config.json.

Copy config.example.json to ~/.agent/config.json and keep only the fields you need — every field is optional and unknown keys (like the "// ..." comments in the example) are ignored, so defaults apply for anything you omit.

The config command

You can manage the config without hand-editing JSON:

computah config path                 # print the config file location
computah config init                 # create a starter config (--force to overwrite)
computah config show                 # print the current effective config
computah config get <key>            # print one value
computah config set <key> <value>    # set a scalar (types inferred: 16384, true, "text")

# MCP servers
computah config add-mcp <name> --command <exe> --arg <a> --arg <b> [--prefer] [--prefer-hint "..."]
computah config add-mcp <name> --url <url> --token <tok>
computah config remove-mcp <name>

# Hooks
computah config set-hook <post_edit|pre_command|post_turn> "<command>"
computah config remove-hook <name>

Writes are a typed round-trip — the file is rewritten as clean, indented JSON. If it contains keys the agent doesn't model (e.g. hand-added "// comment" keys), a config.json.bak backup is made first, so a rewrite never silently drops anything. set rejects unknown keys, so a typo can't corrupt the file.

~/.agent/config.json fields

Hooks

hooks maps a lifecycle point to a shell command. {file} and {cmd} are substituted; a nonzero pre_command exit blocks the command.

"hooks": {
  "post_edit":   "gofmt -w {file}",
  "pre_command": "true",
  "post_turn":   "git status -sb"
}

MCP servers

mcp_servers extends the agent with external MCP tool servers over stdio (a child process) or HTTP. Set prefer: true to steer the model toward a server in the system prompt, and prefer_hint to describe how it should use a non-notes server.

"mcp_servers": {
  "sandbox": {
    "command": "sandbox",
    "args": ["mcp", "-image", "python:3-alpine"],
    "prefer": true,
    "prefer_hint": "Run untrusted or experimental code here, in an isolated container, rather than run_command."
  },
  "remote": {
    "url": "https://mcp.example.com/sse",
    "token": "your-token",
    "headers": { "X-Extra": "value" }
  }
}

Per-server keys: command/args/env (stdio) or url/token/headers/insecure (HTTP); no_prefix registers tools under their own names; prefer / prefer_hint control system-prompt steering.

Memory

computah's memory is engram — a self-hosted memory service (a brain, not a notes folder) that the agent talks to over MCP. It's how the agent recalls decisions, runbooks, and context across sessions and projects, and records durable conclusions as it works.

engram is wired in like any other MCP server — there's nothing computah-specific to enable. Run engram (see its repo), then add it to mcp_servers in ~/.agent/config.json:

"mcp_servers": {
  "engram": {
    "url": "http://localhost:8088/mcp/",
    "no_prefix": true,
    "prefer": true,
    "prefer_hint": "Use engram for durable memory: recall past decisions, runbooks, and context, and record significant conclusions."
  }
}

Or via the CLI:

computah config add-mcp engram --url http://localhost:8088/mcp/ \
  --prefer --prefer-hint "Use engram for durable memory."

engram exposes mem_search, mem_read, mem_write, mem_patch, mem_links, mem_list, and mem_delete; -stdio transport is also available if you'd rather run it as a subprocess than an HTTP endpoint. prefer: true steers the model to reach for memory first; no_prefix keeps the tool names as-is.

Layout

computah/
  main.go              entry — hands off to cmd/
  cmd/                 Cobra command tree (run, exec, eval, dashboard, version)
  internal/
    core/              shared types (Message, Event), event bus, styling, config
    agent/             the engine: sandbox, tool registry, loop, sessions, MCP
    md/                terminal markdown rendering
    tui/               full-screen Bubble Tea interface
    web/               read-only / two-way / headless web dashboard
    tools_ext/         engine tool plug-ins (edits, embeddings/code_search, git)

core imports nothing; agent builds on core; the presentation packages (md, tui, web) and tools_ext build on agent. agent never imports them back — cmd injects the UI and tool registrations through hooks, so the dependency graph stays acyclic.

Requirements

• Go 1.25+
• A local OpenAI-compatible server (LM Studio, etc.) reachable at --url