Status: proposed, awaiting agreement. This distils the master specification in CLAUDE.md and
challenges it where the evidence points elsewhere.
re-code is one terminal application in which a developer can use almost any AI model to do real work on a real codebase. The model does the reasoning. The application supplies everything else: files, shell, git, permissions, context management, and the runtime that serves the model.
The immediate goal is narrower, and it decides priorities:
A Fedora terminal coding agent that actually works with local models, with a UX people enjoy.
The universal-provider vision stays in the architecture, but it must not delay that goal. A product that connects to 20 providers and fumbles a multi-file edit on a local model has failed.
These are the features that justify the product existing. Everything else is table stakes.
- Local models that really work. Explicit context control, tool-dialect handling, and failure recovery built for models that are slower and less reliable than frontier cloud models.
- Radical context honesty. Itemised accounting of every request, with a tested overhead budget. This directly answers the 100,000-token problem.
- Measured model capability. A conformance probe answers "can this model do agent work on this machine?" with a tested result, not a marketing claim.
- Hardware-aware recommendations. They count KV cache and real free VRAM, not just weight size.
- A terminal interface with its own identity that always shows what the agent is doing.
- A respectful guest on your machine. Clear separation of user-managed and app-managed runtimes.
- Natural JetBrains integration, using what the IDEs already expose before building a plugin.
- A desktop GUI (Electron, Tauri or otherwise).
- Bypassing provider authentication, subscription limits or usage controls.
- Telemetry by default (see missing requirements).
- Parity with any other tool's feature list. We take interaction ideas, not templates.
| Spec position | Challenge | Evidence |
|---|---|---|
Ollama is an existing container at localhost:11434 |
It is a Quadlet user service that is currently stopped. A stopped --rm container doesn't appear in podman ps -a. Discovery must read systemd units as well. |
Observed 2026-11-06, see HARDWARE_AND_RUNTIME |
| 19 crates | Seven at first. The others have no boundary that has been proven by a second implementation. | ARCHITECTURE |
| Milestone 1 is a chat client, agent tools come in Milestone 2 | Merge them. A chat client doesn't test the main risk, and the TUI's hardest states only exist with tools. | ROADMAP |
| Context work is Milestone 3 | The ledger and preflight check must exist from the first request. Without them, local agents silently lose their system prompt. | CONTEXT_ENGINE |
| RPM is Milestone 8 | Build a basic RPM early. Packaging surprises are cheap early and expensive late. | ARCHITECTURE |
| A JetBrains plugin is likely | JetBrains IDEs already host ACP agents and expose MCP. A plugin may be needed only for gaps, if at all. | IDE_INTEGRATION |
| OAuth and subscription support for cloud providers | For Claude this isn't available to us. Anthropic doesn't permit third-party apps to offer Claude.ai login. An unmodified Claude Code binary, signed in by the user, is the permitted route. | PROVIDER_ARCHITECTURE |
The specification doesn't address the following. Proposed answers are given. Those that need a decision are repeated in ARCHITECTURE.
| Gap | Why it matters | Proposal |
|---|---|---|
| Undo and checkpoints | The most important safety net for an agent that edits files, and a large UX win. Git alone isn't enough: changes may be uncommitted and the project may not use git. | Snapshot every file before an agent edit. /undo restores per turn. Add to the first milestone. |
| Headless mode | Needed for scripting and CI, and it is how we test the engine without a TUI. | re-code run "prompt" with text or JSON event output. |
| Project trust | A cloned repo could carry hooks, MCP servers or instructions that attack the user. | Ask on first entry. Repo-supplied executable configuration is inert until trusted. |
| Licence | Affects dependencies and contribution, and it is awkward to change later. | Decision needed. |
| Telemetry and privacy | Users of local models often choose them for privacy. | No telemetry. Diagnostic reports are created locally and only on request. |
| Retention | SQLite will hold source code and command output indefinitely. | Inspectable size, per-session deletion, optional age limit. |
| Schema evolution | Config and database formats must survive upgrades. | Versioned migrations, tested from day one. |
| Accessibility | Heavy TUIs can exclude screen-reader and low-vision users. | NO_COLOR, reduced motion, high-contrast theme, no meaning carried by colour alone, plain headless mode. |
| Shared-runtime contention | Your Ollama runs OLLAMA_NUM_PARALLEL=1, and Open WebUI uses the same pod. Sessions can evict each other's prompt cache or queue behind one another. |
Show queueing and cache misses in the UI. Warn on contention. |
| Concurrent instances | Two terminals, one project, one database. | WAL mode and a per-session write lease. A session has one active writer. |
| Offline operation | Local-first must function without a network. | No network needed for local use. Nothing phones home. |
| Model licences | Downloads carry licence terms, some restrictive. | Show the licence before a managed download. |
| Updates | RPM users update through dnf, but others won't. | Package manager only at first. No self-updater. |
- Experienced developer (the initial user): wants control, wants to see the raw truth, and will notice a dropped frame.
- Beginner: should never need to know what
num_ctxis. Advanced settings exist, but they are never required to reach a working session.
Default language is plain ("This model will run partly on your CPU, so it will be slower"), with the technical detail one keypress away.