Mainline CLI
A CLI and skill that record an agent's goals, decisions and rejected paths in Git so the next agent does not repeat them
- 204 ★ on the repository
- Last commit
Extended access
Why this level
- `mainline init` changes repository settings, adds Git refs and notes and installs hooks that fire at the start of an agent session
- The install script is downloaded and executed through `curl ... | bash`
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/mainlineDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- `mainline init` changes repository settings, adds Git refs and notes and installs hooks that fire at the start of an agent session
- The install script is downloaded and executed through `curl ... | bash`
This is third-party code. Review the repository files before installing.
What it does
Mainline saves next to the code what commits lack: the original goal of a task, the reasoning path, decisions made, trade-offs, validation and abandoned routes. Records live in Git's own refs and notes, so they travel with `fetch`, branches, merges and forks, and no separate memory service is needed. The agent follows a short command loop. `mainline preflight` shows earlier intents, collision risks with other agents and constraints. `mainline start` opens a record, `mainline append` captures an important pivot, and `mainline seal` closes the work as a reviewable intent. People keep the reading commands: `mainline status`, `mainline log`, `mainline show` and `mainline hub open` to browse in a browser. Once per repository, `mainline init` writes the settings and installs the skill and hooks for Codex, Claude Code, Cursor and Pi.
Who it is for. Teams where several agents and people work in one repository and need to know why the code looks the way it does.
Good fit when
- Before a refactor or deletion the agent has to learn whether this path was tried before and how it ended
- Two agents change the same business logic and the overlap should surface before a pull request, not at merge
- Code looks odd because of an earlier rollback and the reason is needed before cleanup
- A reviewer wants the original goal and key decisions before reading the diff
Not a fit when
- A typo fix, formatting or an obvious one-line repair: the README itself advises skipping those
- A repository with no Git hosting or shared history: records ride on Git refs, and without a shared remote nobody else reads them
- You need a stable data schema: the project is in public alpha and the schema and agent guidance are still changing
Example request
Before rewriting the export module, run mainline preflight and tell me whether there are recorded decisions or rejected paths for this code.Limitations
The project is in public alpha: the record schema, agent guidance and hosted Hub are still evolving. Records pay off where the work is larger than a small edit, so running the loop for every trifle is not worth it.
`mainline init` configures Git refs and notes and installs the skill and local hooks for Codex, Claude Code, Cursor and Pi, so read `mainline init --help` before the first run. The license is layered: the CLI, skills and hooks are open, while the hosted service and brand are separate. The README installs through a `curl` script, and `go install` is an alternative.
How to disable. Remove the local hooks with the command from `mainline hooks` help, delete the installed `mainline` skill from the agent's skills directory and remove the `mainline` binary. Refs and notes in Git remain in the repository history as ordinary data.
FAQ
How do I install Mainline for Claude Code?
Install the CLI with the README script or `go install`, then run `mainline init --actor-name "name"` in each repository. The command writes the settings and installs the skill and local hooks, Claude Code included. The global skill is updated with `npx --yes skills add mainline-org/mainline --skill mainline --agent claude-code --global --yes`.
Where are the records stored?
In Git itself: the event log lives in refs and commit pins in notes. There is no separate memory server, and records spread through `fetch`, branches and forks.
What does the agent do step by step?
Runs `mainline preflight --json`, then `mainline start` with the task description, `mainline append` for important decisions along the way and `mainline seal --prepare` and `mainline seal --submit` at the end. Code edits go as usual.
Is there evidence it helps?
The README describes a controlled test: 8 scenarios, 3 seeds, 2 modes. With intent-first there were 0 forbidden-list violations, with code-first 9. Methodology and caveats are in `docs/eval-results.md`.
How is Mainline different from entire-cli?
entire-cli ties agent session history to commits. Mainline writes goals, decisions and rejected paths as separate records in Git and shows them to the agent before the edit, together with overlaps from other agents.
Discussion
No questions or reviews yet.
Related
CLI toolsWork modes for AI coding agents: a light solo mode for daily tasks and /man with a plan, checks and review for big changes
Over twenty skills for coding agents: MCP and hooks, plan mode, a bug-fix protocol, prompting and a bash safety hook
One desktop window for Claude Code, Codex, Gemini CLI and OpenCode: terminals, pull requests, diffs and approvals
A CLI and MCP server where parallel coding agents declare what they will change and see intent conflicts before any code
A 13-skill delivery workflow for coding agents: from idea to plan, review, security audit, tests and a shipped pull request
A Python terminal coding agent in the manner of Claude Code: reads the repository, edits files, runs commands, with memory, sub-agents and MCP
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Mainline (this card) | no | 204 | |
| Entire CLI | no | 5,310 | ties agent session history to commits, without decision records or overlap checks between agents |
| Beads | no | 28,540 | an agent task tracker with a dependency graph rather than a decision log in Git |
README in short
The README explains four scenarios: not repeating rejected paths, catching logical conflicts before a Git conflict, reading constraints before editing risky code and reviewing intent alongside the diff. A quick start, the agent command loop, team collaboration through Git and the results of an 8-scenario test follow.