locode-exec 0.1.10

Minimal headless runner for the locode agent engine - one JSON report on stdout
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

# LoCode

A Rust-based custom coding agent: the sample → dispatch → append loop, a typed
tool registry, faithful per-harness tool packs, and a provider/wire abstraction
— shipped as a set of library crates plus the `locode` binary (run
`locode -p "say hi"` for a headless rollout, or `locode` without `-p` for an
experimental interactive TUI).

## Why

LoCode is a distilled re-implementation of the agent cores of four studied
coding harnesses (Claude Code, Codex, Grok Build, opencode). Each harness pack
reproduces its harness's real tools and system prompt — names, schemas, caps,
quirks — so different harness designs can be compared honestly, A/B, on the same
engine and the same provider wire. The tool packs are also a first-class library
surface: downstream consumers can drop the tools into their own agent loop
without using our engine.

The reproduction is deliberately scoped. What each pack faithfully mirrors is
its harness's **system prompt** and its **tool behavior** — and the tool surface
is the six core tools every coding agent shares (shell, read, write, edit, list,
search). Everything above that line — memory files (`AGENTS.md` and friends),
skills, and the fancier engine behaviors — is implemented once and shared across
all packs rather than reproduced per harness, so the fancier per-harness
features are not modeled. That core is enough to run most coding-benchmark
evaluations and everyday tasks, but it is not exhaustive: LoCode is built for
evaluation and research, not as an end-user product.

## Install

Prebuilt `locode` binaries for macOS and Linux (one command to install,
re-run it to update):

```sh
curl -fsSL https://raw.githubusercontent.com/luolc/locode-core/main/install.sh | bash
```

The script installs to `~/.locode/bin` (override with `LOCODE_BIN_DIR`),
verifies the sha256 checksum, and puts the binary on your PATH. Pass a version
for a specific release: `… | bash -s 0.1.10`. Then run `locode` for the
interactive agent or `locode -p "task"` for a headless one-shot. The search
tools shell out to [ripgrep](https://github.com/BurntSushi/ripgrep) — have `rg`
on PATH or point `LOCODE_RG_PATH` at a binary.

Or build from source: `cargo install --git https://github.com/Luolc/locode-core locode-app`.

## Quick start

```sh
export LOCODE_API_KEY=…      # required (except with --api-schema mock)
export LOCODE_BASE_URL=…     # optional: provider endpoint override
export LOCODE_MODEL=…        # optional: model id override

# One task, headless: one JSON report on stdout, diagnostics on stderr.
locode -p "summarize this repo" --harness grok
# …or from a source checkout, without installing:
cargo run -p locode-app -- -p "summarize this repo" --harness grok
```

Select the provider wire with `--api-schema` (`anthropic` | `openai-responses`
| `mock`, where `mock` runs keyless) and the stdout artifact with
`--output-format` (`json` | `stream-json` | `text`). See `locode --help` for the
full surface.

`LOCODE_BASE_URL` defaults to the wire's native endpoint
(`https://api.anthropic.com` for `anthropic`, `https://api.openai.com` for
`openai-responses`); point it at any compatible gateway (e.g. OpenRouter) to
reach other providers over the same schema. `LOCODE_API_KEY` must match
whichever endpoint you target.

## Interactive app (`locode`)

LoCode is primarily a headless engine for evaluation and data pipelines. It
also ships an **experimental** interactive terminal UI, built in this repo as
separate crates (`locode-tui` = components/library, `locode-app` = the `locode`
binary) layered on the core (ADR-0019). It drives one session interactively:
type a prompt, watch tool calls and the reply stream in, approve or deny tool
calls, cancel a turn with Esc, and continue the conversation. Treat it as a
convenience for exploring the engine, not a supported product.

```sh
# Keyless demo (scripted mock wire — no API key):
locode --api-schema mock

# Against a real wire, with tool approvals prompted:
LOCODE_API_KEY=… locode

# …or skip approvals (auto-allow every tool, lift the path jail):
LOCODE_API_KEY=… locode --yolo
```

## Development

To build and test everything:

```sh
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps
```

## Custom providers

The provider surface is open: implement the `Provider` trait for any backend,
register it under a name, and your own binary crate gets the entire CLI —
flags, report envelope, exit codes — with your provider selectable at run time:

```rust
use locode_exec::{ProviderRegistry, main_with};

fn main() -> std::process::ExitCode {
    let registry = ProviderRegistry::builtin()
        .register("my-wire", |init| my_wire::build(init));
    main_with(registry)
}
```

`--api-schema my-wire` then selects it; unknown names fail before the run
starts, listing what's registered.

## [Disclaimer](DISCLAIMER.md)

This is a personal project and is not affiliated with any company. The content
does not reflect any specific company's projects, products or internal work.