reposix¶

Agents already know cat and git. They don't know your JSON schema.

reposix exposes REST-based issue trackers (Jira, GitHub Issues) and wikis (Confluence) as a real git working tree. An autonomous LLM agent can reposix init, cat, grep, edit, and git push tickets without learning a single Model Context Protocol (MCP) tool schema or REST SDK surface. It runs alongside REST — the other 20% of operations (complex JQL, bulk imports, admin) keep using the API directly. reposix handles the 80% where an agent just needs to read, edit, and push.

~94% fewer output tokens · ~75% cheaper than GitHub-MCP for the same read-3-issues + edit-1 + push task, from 6 live agentic sessions (token economy)
6 ms cached read · 278 ms cold init — simulator, CI-canonical (latency)
5 ways to install — curl, brew, cargo binstall, or irm (first-run.md)

See reposix end-to-end in under 90 seconds — init, cat, edit, push, no MCP tool schema in sight.

Video not playing? Download the launch animation (mp4).

reposix loop vs MCP loop¶

sequenceDiagram autonumber participant Agent participant reposix as reposix loop participant MCP as MCP loop Note over Agent,reposix: git-native loop · ~1.2k output tokens (live) Agent->>reposix: cat issues/0001.md Agent->>reposix: sed -i ... && git add Agent->>reposix: git push Note over Agent,MCP: MCP tool loop · ~21k output tokens (live) Agent->>MCP: list_tools() Agent->>MCP: call_tool(get_issue, {id:1}) Agent->>MCP: call_tool(update_issue, ...) Agent->>MCP: call_tool(post_comment, ...)

Same workflow, two loops. The reposix loop reuses cat/sed/git — vocabulary the agent already has — and pushes one commit. The MCP loop discovers tools, then issues one call per field mutation. The gap is measured live: the git-native arm generates ~94% fewer output tokens for the identical GitHub task (benchmarks/token-economy.md).

30-second install¶

curl (Linux/macOS)PowerShell (Windows)Homebrewcargo binstall

curl --proto '=https' --tlsv1.2 -LsSf \
    https://github.com/reubenjohn/reposix/releases/latest/download/reposix-installer.sh | sh

powershell -ExecutionPolicy Bypass -c "irm https://github.com/reubenjohn/reposix/releases/latest/download/reposix-installer.ps1 | iex"

brew install reubenjohn/reposix/reposix

cargo binstall reposix-cli reposix-remote

Full step-by-step in first-run.

Build from source (advanced)

The supported install path is the package-manager band above (curl / Homebrew / cargo binstall / PowerShell irm). Build-from-source is for contributors and for platforms not covered by the prebuilt binary archives.

git clone https://github.com/reubenjohn/reposix && cd reposix
cargo build --release --workspace --bins
export PATH="$PWD/target/release:$PATH"
reposix sim &                                             # start the simulator on :7878
reposix init sim::demo /tmp/reposix-demo
cd /tmp/reposix-demo && git checkout -B main refs/reposix/origin/main && cat issues/1.md

After init, agent UX is pure git: cat, grep -r, edit, git commit, git push. The bootstrap takes ≤ 278 ms against the simulator (CI-canonical; a warm dev machine is several times faster).

After — one commit¶

Create the demo working tree, then edit, commit, and push:

reposix sim &                              # start the simulator on :7878
reposix init sim::demo /tmp/reposix-demo   # create the demo working tree
cd /tmp/reposix-demo && git checkout -B main refs/reposix/origin/main

cd /tmp/reposix-demo
sed -i 's/^status: .*/status: in_progress/' issues/1.md
echo $'\n## Comment\nReproduced — investigating root cause.' >> issues/1.md
git commit -am "1: in progress" && git push

The audit trail is git log. No SDK to vendor; no schemas to load.

Mental model in 60 seconds → How it complements MCP and SDKs →

Tested against¶

reposix's 6 ms cache read is measured against the in-process simulator, but the architecture is exercised end-to-end against three real backends sanctioned by the project owner for aggressive testing:

Confluence — TokenWorld space (Atlassian Cloud).
GitHub — reubenjohn/reposix issues (this project's own tracker).
JIRA — project TEST (overridable via JIRA_TEST_PROJECT).

Latency for each backend is captured in docs/benchmarks/latency.md. Sim cold init is 278 ms (soft threshold 500 ms); list-issues 7 ms; capabilities probe 5 ms.

Real-backend numbers are already captured: get-one-record is 320 ms against GitHub and 202 ms against Confluence (latency).

Connector capability matrix¶

The four built-in backends differ in capabilities. reposix doctor prints your configured backend's row at runtime (see exit codes for harness integration); the static matrix is also here for at-a-glance reading:

Backend	Read	Create	Update	Comments	Delete	Versioning
sim	yes	yes	yes	in-body	yes	strong
github	yes	no	no	no	no	timestamp
confluence	yes	yes	yes	no (see below)	yes	strong
jira	yes	yes	yes	no	yes	timestamp

Comments footnote

reposix-confluence has a list_comments/list_attachments API surface in the crate, but nothing in the cache or materializer wires it into a working tree — no file, no git diff, no push path reaches it. Treat Confluence's Comments cell as "no" until a future milestone lands the wiring.

GitHub Issues is currently read-only — create / update / delete return Error::NotSupported, and its ETag concurrency is not yet plumbed (hence timestamp). JIRA and Confluence round-trip the full write surface via git push. For the canonical struct + per-backend constant, see crates/reposix-core/src/backend.rs (BackendCapabilities); each connector's CAPABILITIES row is regression-tested against its observable behavior (capabilities_match_create_impl).

Where to go next¶

💡 Mental model in 60 seconds — three keys to the design (clone = snapshot · frontmatter = schema · git push = sync verb).
⚖️ reposix vs MCP and SDKs — positioning, with measured numbers per row.
🔗 How it works — the filesystem layer, the git layer, time travel, and the trust model.
📊 Latency envelope — the v0.9.0 measured numbers.
🪙 Token economy — the live ~94% output-token / ~75% cost reduction vs GitHub-MCP, methodology and captures.

What it looks like underneath¶

reposix has three pieces — a local bare git repository built from REST responses (with file content fetched lazily), a git remote that handles both reads and pushes by translating to API calls, and reposix init (a one-shot bootstrap). Two guardrails are load-bearing for autonomous agents: push-time conflict detection rejects stale-base pushes with the standard git "fetch first" error so an agent recovers via git pull --rebase && git push, whether the base moved via a peer git-side push, an external REST write, or an SoT deletion (v0.14.0 RBF-LR-03 fix — proven GREEN on git 2.25.1 via the import path; verification on the modern-git read path (git ≥2.34) is still open, see backlog item DRAIN-07); the fetch size limit caps git fetch and emits a stderr message that names git sparse-checkout as the recovery move. An agent unfamiliar with reposix observes the error, runs sparse-checkout, and recovers with no human prompt engineering.

The detail of how each piece works lives in How it works. The reference material — frontmatter schema, simulator HTTP surface, testing targets — is in Reference.

Honest scope

Built across autonomous coding-agent sessions; v0.9.0 architecture pivoted from a virtual filesystem to git-native partial clone (2026-04-24). Treat as alpha — but every demo on this site is reproducible on a stock Ubuntu host in under five minutes. The token-economy headline is now live: 6 real agentic sessions (median-of-3 per arm) against the same GitHub backend measured ~94.3% fewer output tokens and ~74.9% lower cost per session for the git-native arm (see benchmarks/token-economy.md for the four-axis table and caveats — including that GitHub write-back is read-only in this cut).