λgitsite

~ober/jerboa-code

Imported from ~/mine/jerboa-code

download snapshot

about

# jerboa-code

**A portable AI coding agent written in [Jerboa](https://git.jerboa.sh/ober/jerboa) Scheme.**

`jcode` is a terminal coding agent — think opencode / aider / Claude Code — that
compiles to a standalone binary without a Node or Python runtime. It talks to 14
LLM providers (cloud and local), drives your editor through a real tool loop,
and ships a reliability layer that makes even small self-hosted models call
tools dependably.

```
┌────────────────────────────────────────────────────────────────┐
│ jcode                                          BUILD · sonnet    │
│                                                                  │
│  › add a --json flag to the status command                       │
│                                                                  │
│  ● read   src/cli.ss                                             │
│  ● edit   src/cli.ss  (+12 −1)                                   │
│  ● bash   make test            411 passed, 0 failed              │
│                                                                  │
│  Done — `--json` emits the status block as a JSON object.        │
└────────────────────────────────────────────────────────────────┘
```

## Why it exists

- **Portable.** One standalone binary. Runs on macOS, Linux, FreeBSD,
  and Android (via Termux). No Node, no Python, no ecosystem.
- **Provider-agnostic.** Anthropic, OpenAI, Google, OpenRouter, DeepSeek, xAI,
  Groq, Mistral, Together, Cerebras, Perplexity — plus local **Ollama** and
  **MLX**. Switch with `/model` mid-session.
- **Reliable on small models.** A native port of [forge](https://github.com/azambelli/forge)
  plus [ATLAS](docs/FORGE.md#the-atlas-reliability-layer)-style verify-and-repair
  wraps every call: prose-to-tool rescue, step enforcement, verify-gate, and
  best-of-k. Always on, every provider.
- **Delegation built in.** Named sub-agent roles for the `task` tool —
  read-only `delegate`, docs-scoped `doc-explorer`, gated `implementer`
  (BLUEPRINT → approve → EXECUTE) — with enforced write scopes, per-agent
  model routing via `jcode.json`, and plan-lifecycle skills
  (`create-plan` / `resume-plan` / `generate-handover`). See
  [docs/agents.md](docs/agents.md).
- **A real TUI.** termbox-based panels, markdown + syntax highlighting, live
  diffs, themes, a sidebar with token / cost / GPU stats.

## Quickstart

You need a C compiler and Rust/Cargo. `make build` and `make binary` use a
local Jerboa toolchain when present, otherwise they fetch the configured
release bundle into `.jerboa/bin`. See
**[docs/getting-started.md](docs/getting-started.md)** for the full setup.

```bash
git clone https://git.jerboa.sh/ober/jerboa-code && cd jerboa-code

make build          # compile src/ → lib/
make binary         # produce the standalone ./jcode
./jcode keys add anthropic     # store an API key (encrypted)

./jcode              # interactive REPL
./jcode --tui        # full terminal UI
./jcode -p "explain this repo"   # one-shot prompt
```

## Documentation

| Doc | What's in it |
|---|---|
| **[Getting started](docs/getting-started.md)** | Prerequisites, building on every platform, configuration, keys, first run. |
| **[CLI reference](docs/cli.md)** | Every subcommand, flag, slash command, and environment variable. |
| **[Architecture](docs/architecture.md)** | The agent loop, module map, and how a turn flows through the guardrails. |
| **[Providers & models](docs/providers.md)** | The 14 providers, model registry, per-model sampling, and hardware tiers. |
| **[Tools](docs/tools.md)** | The agent's toolbox (file, bash, web, git, patch, task, MCP) and the safety model. |
| **[Named agents & plans](docs/agents.md)** | Sub-agent roles with enforced write scopes, per-agent models, gated execution, and the plan-lifecycle skills. |
| **[Verify-gated runs](docs/verified.md)** | `jcode verified`, cookbook-guided local-model runs, MCP tools, write scopes, JSON status, and troubleshooting. |
| **[TUI](docs/tui.md)** | Layout, keybindings, themes, and the rendering features. |
| **[Forge & ATLAS reliability](docs/FORGE.md)** | Guardrails, workflows, verify-gate, best-of-k, the proxy, and the eval harness. |
| **[Remote & Android](docs/remote.md)** | `serve` / `relay` / `connect` and the thin-client architecture. |
| **[Threat model](docs/threat-model.md)** | Assets, trust boundaries, controls, and residual risks for production use. |
| **[Credential handling](docs/credential-handling.md)** | API key sources, storage, logging, tracing, and release checks. |
| **[FFI boundary](docs/ffi-boundary.md)** | Native components, ownership rules, generated artifacts, and audit procedure. |
| **[Release evidence](docs/release-evidence.md)** | SBOM, reproducibility, binary smoke, and release-bundle contents. |

See **[docs/](docs/)** for the full index.

## Build targets

`make build` · `test` · `audit` · `sbom` · `reproducibility-report` ·
`release-evidence` · `run` · `run-tui` · `binary` · `install` · `linux` ·
`linux-amd64` · `linux-arm64` · `freebsd` · `android`.
Run `make help` for the complete list.

## Layout

```
main.ss              entry point
src/jcode/
  core/       agent loop, config, sessions, guardrails plumbing, ATLAS
  provider/   the 14 LLM providers + per-model sampling
  tool/       file, bash, web, git, patch, task, repomap, lsp
  guardrails/ rescue, validator, step-enforcer, respond, error budget
  proxy/      OpenAI-compatible guardrail proxy
  eval/       deterministic ablation harness
  ui/         cli, tui-*, serve/relay/connect
  mcp/        MCP client
```

Source is **Jerboa `.ss`**, compiled by `jerbuild` to Chez `.sls` under `lib/`.
See [`AGENTS.md`](AGENTS.md) for the language reference and [`CLAUDE.md`](CLAUDE.md)
for contributor conventions.

recent commits