Metadata-Version: 2.4
Name: routemark
Version: 0.1.0b14
Summary: Let Claude Code or Codex hand execution work to a cheaper coding agent on your machine, review it, and merge exactly what passed.
Keywords: claude-code,codex,opencode,coding-agent,delegation,code-review,sandbox,llm
Author: Saar Inc.
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Project-URL: Homepage, https://routemark.ai
Project-URL: Repository, https://github.com/abhayvc/routemark
Project-URL: Changelog, https://github.com/abhayvc/routemark/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# Routemark

Routemark keeps the powerful model you already pay for in charge, and lets it
hand execution work to a cheaper coding agent on your own machine. That model,
**the Controller** (Claude Code or Codex), writes the task; a **delegate** (another
coding-agent harness, such as OpenCode, with a cheaper model) does the work in a
private copy; the Controller reviews the result, and only what was reviewed and
passed is merged into your repository.

It is not a model, not a harness and not a service. It is a command-line tool and
a set of skills your Controller reads, running on one machine. It calls no service
of its own: your delegate's harness talks to its own provider under its own login.
What Routemark keeps is in one directory, `~/.routemark`, plus one
`routemark.toml` file in each project you add.

## What it guarantees

A project is *open* by default: the delegate runs as you, unsandboxed. A
*sandboxed* project runs it inside a macOS sandbox; you make one with
`routemark project add DIR --containment sandboxed`.

These hold because Routemark enforces them, not because a model was asked nicely:

- **A delegate works in its own private copy and never writes to your real
  repository.** On a *sandboxed* project it runs inside a macOS sandbox that lets
  it change only that copy, and Routemark checks the sandbox holds on your machine
  before any work starts.
- **What merges is exactly the tree that was judged.** If your branch moved while
  the delegate worked, the judged change is applied on top of the branch as it is
  now, checked again, and only then merged.
- **A credential is never shown, and stops the merge.** What could merge is
  scanned for credentials. One the delegate brought in is never printed, and the
  merge waits until you, in person, clear that finding with a reason.
- **Nothing merges without a review on record**, unless you waive the review
  yourself. Waiving a review and clearing a credential finding work only when a
  person runs them at a terminal; a Controller is told to hand them to you.
- **Checks the Controller keeps hidden stay hidden.** The delegate never sees them.

On an *open* project the delegate is not sandboxed: it can see
what you can see, your files and your network alike, and `routemark project add`
says so. There the guarantees hold against mistakes and ordinary misbehaviour,
not against a delegate deliberately attacking Routemark's own files; the sandbox
is where they hold against that.

## How it behaves

- **A merge never overwrites work you have not committed.** It stops before
  anything changes and names the files.
- **Routemark never stops a run on its own.** A run that looks stuck is reported,
  with the facts; only a person stops it, with `routemark stop`.

## What it does not do

- It does not pick models. The Controller recommends a harness, provider and
  model, you decide, and Routemark records what worked on this machine as advice
  for next time. It never permits or refuses a run because of a model.
- It does not judge providers. It ships no opinion on vendors, model families or
  countries.
- It does not get between you and your Controller. How far the Controller goes
  without asking you is agreed between the two of you; it is not a Routemark
  setting.

## Install

You need macOS, git, uv (or pipx), and Claude Code or Codex. uv brings its own
Python; pipx needs Python 3.11 or later (a stock Mac's `/usr/bin/python3` is 3.9).

```
uv tool install routemark
```

or `pipx install routemark`. Check it took:

```
routemark --version
```

## A first delegation in ten minutes

**The one ordering rule: install Routemark, then `routemark skills install`, and
only then open your Controller.** The Controller reads a copy of the skills that
`skills install` makes, so after installing or upgrading Routemark, run it again
before you start a new Controller session. It links into a Controller it can see,
so run Claude Code (or Codex) once beforehand: that is what creates `~/.claude`
(or `~/.codex`).

Link Routemark's skills into your Controller. The first command refreshes
Routemark's own copy of the skills, shows what it would link, and links nothing
into your Controller; the second makes the links:

```
routemark skills install
```

```
routemark skills install --yes
```

See what is on this machine: the delegate harnesses, and the providers and
models each one already has.

```
routemark discover
```

Now open Claude Code or Codex in a git project and ask it to delegate a task
with Routemark, for example: *"Using Routemark, delegate this to OpenCode: add a
short Getting started section to README.md. Review it and merge it if it is
good."* If there is no delegate on the machine yet, the Controller offers to set
one up with you, asks before installing anything, and has you log in to the
harness yourself; Routemark never handles a credential's value.

What the Controller then runs, and what you will recognise on screen:

1. `routemark delegate`: prints `Run 20261001T135234-a212c6. While it is going: ...`
   and hands the task to the delegate in a private copy.
2. It waits for the delegate to finish: `opencode finished in 41.2s.`
3. It judges the result: `The result of run ... is the tree 4461ffb3...`,
   followed by every check it ran and the exact diff that would merge.
4. After its review, and your yes: `routemark merge`, which prints
   `What merged is the tree that was judged: 4461ffb3...`.

Every command that starts or finishes a step prints the next one to run, filled
in, except the reviewer's own harness and model, which only you know. `routemark --help` lists them all.
The quickstart,
[`docs/quickstart.md`](https://github.com/abhayvc/routemark/blob/main/docs/quickstart.md),
is the full first run, with the output at each step.

## The console

```
routemark console
```

opens a read-only page in your browser: what is waiting on you, what is running,
what finished, and the track record. It changes nothing, and it ends when its
terminal does (Ctrl-C). `routemark console --no-open` opens no browser: of the
two addresses it prints, paste the second, one-time address into the browser you
want.

## What it costs you

`routemark report` and the console lead with **the Controller's own usage per
merged task**, named for the Controller it was read from (Claude's, Codex's, or
both): the tokens your Controller spent on each delegated task, from the moment
it started on the task to the merge, in fresh tokens (input, output and cache
writes, with cache reads shown beside and never in), by model where the session
records it (Claude Code's do; Codex's are not split by model). It is worked out
when you ask, from your Controller's own session records on this machine and
Routemark's run records. It is never estimated: where a session is gone or
cannot be read, the figure is absent and says so.

Beside it stands only something measured on this machine: the same figure over
work your Controller did itself, recorded with `routemark direct begin` and
`routemark direct end`, with how many tasks it rests on and the date of the
latest. Nothing is netted and nothing is turned into money.

The delegate's own tokens are shown too, as the delegate's: what it spent on the
merged tasks, beside your Controller's own estimate of doing the work itself
where it gave one, and set against nothing.

## Where the data lives

Everything Routemark keeps is under one directory, `~/.routemark` (set
`ROUTEMARK_HOME` to put it elsewhere). `routemark home` prints where it is. In it
are the run records (the track record your reports are read from), the private
copies delegates work in, and the copy of the skills your Controller reads.

Outside it is only what you agree to: the `routemark.toml` in each project you
add, the links `routemark skills install --yes` makes into your Controller
(`~/.claude/skills`, `~/.codex/skills`), and, if you install the launcher, its
launchd entry in `~/Library/LaunchAgents` and its log in
`~/Library/Logs/routemark`.

```
routemark disk
```

says how much each project is using.

```
routemark clean-up
```

takes back what merged and abandoned attempts left behind. A merge already
reclaims its own working area; a run's record stays. `routemark disk --sessions`
lists the harness sessions Routemark started, with the harness's own delete
command for each: Routemark never deletes one.

## The honest limits

- **macOS today.** Linux is next, for open projects; sandboxed projects on Linux
  come later. Windows is not supported.
- **Two Controllers and two delegate harnesses have skills:** Claude Code and
  Codex drive; OpenCode and Prime are the delegates. OpenCode runs on open and
  sandboxed projects, Prime on open projects only.
- **A Codex Controller and a sandboxed project.** Codex runs its commands in a
  sandbox of its own, and macOS will not start a second sandbox inside it. So a
  Codex Controller reaches a sandboxed project through Routemark's launcher
  (`routemark launcher install`, which shows what it creates and asks first), or
  by running `routemark delegate` outside its sandbox with your approval.
- **These are beta releases**, numbered `0.1.0b`; `routemark --version` says which
  you have. They have been run on two Macs with Claude Code and Codex driving,
  OpenCode and Prime delegating, on real providers. `0.1.0` comes after three
  walk-throughs by a person: Claude Code on a Mac with no delegate at all, Codex
  on that Mac, and Claude Code on Linux.

## Removing it

```
routemark skills remove --yes
```

```
uv tool uninstall routemark
```

Run `routemark launcher remove` first if you installed the launcher. `skills
remove` takes away only the links; the state home is yours to delete, and
`routemark home` says where it is.

## Reporting a problem

Open an issue at https://github.com/abhayvc/routemark/issues, with what you ran
and what it printed. An id like `MERGE-4` in Routemark's output names the rule it
applied; quote it. Read what you paste before you send it: a terminal can hold
more than Routemark printed.

## Licence

What this package ships, the command line, the loop, the sandbox and the
one-machine console, is free under the Apache License 2.0 (see `LICENSE` and
`NOTICE`), copyright Saar Inc. The name Routemark is Saar Inc.'s mark, and the
licence grants no right to it. Paid features, when there are any, will be a
separate package under their own terms, offered inside the console when you
meet a limit; never in the command line, at install, or for safety.

## From the repository

[`CHARTER.md`](https://github.com/abhayvc/routemark/blob/main/CHARTER.md) says what Routemark
does and what it guarantees.

```
uv sync
```

Build the wheel and prove it works when installed (the wheel and the sdist are
left in `dist/`), and run the tests:

```
.venv/bin/python scripts/build_and_verify_package.py --out dist
```

```
.venv/bin/python -m pytest -q
```
