- Website: https://mainline.sh
- Hosted Hub: https://mainline.sh/hub/
- Detailed reference: docs/reference.md
- 中文版本: README.zh.md
Git for the AI era.
Mainline_Git_Memory_System_Overview_1080p_compressed.mp4
Mainline lets agents save developer intent and decisions to Git alongside the code.
Git already records the history of the code. Mainline adds the engineering judgment behind agent work to the same collaboration layer: the original goal, reasoning path, key decisions, trade-offs, validation, explicit constraints, abandoned routes, and the commit that eventually carried the work.
Teams do not need to keep long AI transcripts around, and they do not need to invent a separate shared memory service. Agents read prior judgment from Git, do the work, and write the new judgment back to Git.
Agents can move fast, but code alone does not carry the full history. Mainline is not another knowledge base for humans to maintain; it is a tool agents can read and write as naturally as they use Git.
Some approaches were tried, rejected, and then disappeared from the code.
Maybe the team once tried to process billing events through a Redis queue, then abandoned it after replication lag caused duplicate charges. The next agent may grep its way to a half-finished TODO and decide it only needs to complete the work. Mainline tells the agent before it edits: this path was already tried, where it failed, and why it should not be revived casually.
Git can detect two edits to the same line. It cannot tell when two agents are changing the same product logic in incompatible ways.
If another agent has already started changing a billing rule, there may be no PR yet, but there is already an intent. Other agents can see that intent during preflight and avoid the collision from the start by changing scope, splitting the boundary, or syncing with the teammate first.
Some code looks odd because it carries real history, and comments rarely capture all of it.
An auth middleware path may exist only because a previous cleanup caused a rollback. Mainline can put the rollback reason, module constraints, and related intent in front of the agent before it edits, so the agent understands why that code is not safe to "clean up" blindly.
Reviewers should see more than the code diff. They should see the implementer's original goal, reasoning path, and key decisions.
Review no longer has to start by guessing why a diff exists. The reviewer can read the intent first, then verify whether the implementation matches that intent. The conversation moves earlier, toward direction, risk, and trade-offs, instead of only catching syntax and edge cases at the end.
Mainline's storage and collaboration model is designed around Git.
| Capability | How Mainline Works |
|---|---|
| Data lives in the Git repo | Intent event logs live in Git refs; commit pins live in Git notes |
| Git-native workflow | Intent travels through fetch, branch, merge, and fork workflows |
| Agents read and write automatically | Hooks, the Mainline skill, and the CLI let agents read history, record judgment, and seal intent |
| No vendor lock-in | Codex, Claude Code, Cursor, Pi, Copilot, and internal agents can work from the same repo facts |
| No disruption to your workflow | Keep using your editor, agent, GitHub / GitLab PRs, and CI as usual |
Mainline does not replace Git. It puts the engineering judgment future agents need back into Git.
Mainline is mainly operated by agents. After the initial setup, developers do not need extra daily commands, and their existing AI coding workflow does not change.
It plugs into agent workflows through three pieces:
- Agent hooks: sync repo intent at session start and inject fresh state;
- Mainline skill: tells the agent when to read history, record judgment, and stop;
- CLI: provides auditable commands such as
preflight,start,append, andseal.
If an agent does not have a hook integration yet, it can still use Mainline through the skill and CLI. The rule stays the same: read prior judgment from Git before editing, then write the new judgment back to Git when the work is done.
A typical agent run looks like this:
mainline preflight --json
mainline start "clean up old export logic" --json
mainline append "confirmed the legacy CSV route is still used for overnight enterprise reconciliation" --json
mainline seal --prepare --json > .ml-cache/seal.json
mainline seal --submit --json < .ml-cache/seal.jsonThose steps map to the agent loop:
- Get context: the agent checks the current branch, prior intents, collaboration risks, and relevant constraints.
- Do the work: it reads code, edits, validates, and responds to reviewer feedback as usual.
- Record pivots: when a decision, rejected path, risk change, or validation result matters,
appendrecords it. - Seal the decision record:
sealturns the work into intent that can be reviewed, synced, and retrieved by future agents. - Let it flow through Git: Git refs and notes carry the intent through fetch, branch, and merge workflows.
Future agents do not have to search an old chat transcript for clues. They inherit context from the history the repository already carries.
Install the CLI:
curl -fsSL https://raw.githubusercontent.com/mainline-org/mainline/main/install.sh | bash
mainline versionYou can also install with Go:
go install github.com/mainline-org/mainline@latestDownloadable release archives and checksums are published on GitHub Releases.
mainline version only verifies that the CLI is installed and on your PATH.
mainline doctor --setup is a per-repository wiring check and expects to run
inside a Git repository.
Initialize each repo once:
cd your-repo
mainline init --actor-name "alice"mainline init will:
- write repo-local Mainline configuration;
- configure the required Git refs and notes;
- install the Mainline skill;
- install repo-local hooks for supported agents such as Codex, Claude Code, Cursor, and Pi;
- record the current
mainHEAD as the coverage baseline for an existing repository.
If a repository was initialized before a given agent hook existed, install hooks again:
mainline hooks install
# or only install one agent integration
mainline hooks install --agent piUse the skills CLI to update the global skill:
npx --yes skills add mainline-org/mainline --skill mainline --agent codex claude-code cursor pi --global --yesMost day-to-day commands are run by agents. Humans usually read state, inspect intent, and open Hub.
mainline status --actionable
mainline log
mainline show <intent_id>
mainline gaps
mainline hub openHub lets you browse intent history, pending work, file-level context, coverage gaps, risks, and collaboration signals.
For static export:
mainline hub export ./mainline-hubThe public hosted Hub for Mainline is https://mainline.sh/hub/.
The detailed reference covers install variants, recovery rules, hook behavior, webhooks, configuration, static Hub publishing, storage layout, and development commands: docs/reference.md.
Mainline gets its collaboration model from Git.
Teammates, branches, forks, CI, and other agents can all share the same intent history as long as they can reach the same repository. A teammate should not have to ask "why did yesterday's agent do this?" or dig through somebody else's local chat transcript.
Typical collaboration patterns:
- New teammates read
mainline logand Hub to catch up on recent project judgment. - Reviewers read intent before reading the diff.
- Agents see nearby intent during preflight and avoid starting with a conflicting plan.
- Fork contributors can publish their actor log, and upstream maintainers can explicitly accept it.
- After merge, the commit and intent are pinned together as context for the next round of work.
Fork contributor flows, external PRs, and actor-log import are covered in docs/reference.md.
Use Mainline before agent work that is more than a tiny edit:
- architecture changes,
- refactors and migrations,
- deletions,
- auth, billing, permissions, and data model changes,
- release and CI changes,
- questions like "can we delete this?",
- questions like "was this tried before?",
- any work where another agent or teammate might be operating nearby.
Skip it for narrow typo fixes, pure formatting, and one-line obvious syntax repairs.
We ran a controlled eval: 8 scenarios, 3 seeds, 2 modes.
| Mode | Forbidden-list violations | Consistency |
|---|---|---|
| Intent-first | 0 | 0/8 fixtures fail |
| Code-first | 9 | 2/8 fixtures fail consistently |
The wins showed up where code could not reveal the answer: abandoned approaches, superseded decisions, and conventions outside source code.
Read the full methodology and caveats in docs/eval-results.md.
- Detailed reference: docs/reference.md
- Eval report: docs/eval-results.md
- Intent Record Spec: docs/specs/intent-record-v0.md
- Agent Context Protocol: docs/specs/agent-context-protocol-v0.md
- Agent Autonomy Stop Lines: docs/specs/agent-autonomy-stop-lines-v0.md
- Contributing: CONTRIBUTING.md
- Security: SECURITY.md
- Changelog: CHANGELOG.md
go build -o mainline .
make quick-test
make test
make lintCore subsystems are covered with property-based tests. The fast PR gate is
make quick-test; broader PBT coverage is documented in
docs/reference.md.
Mainline is in public alpha. The CLI, skill, hooks, Hub, and Git refs / notes storage model are usable today, but the schema, agent workflow guidance, and Hosted Hub experience are still evolving.
Mainline is a good fit for teams that already use agents in real engineering workflows and are starting to worry about context getting lost. Feedback is welcome.
Mainline uses a layered licensing model. The local CLI, agent skills, hooks, adapters, libraries, and protocol specs are intended to be open and embeddable. Docs and examples are licensed for reuse with attribution. Hosted service surfaces and brand assets remain separate.
See docs/reference.md and LICENSE for details.