Landrace

Landrace takes issues from your issue tracker; each one it works on is an item.

• Agents work, code decides. The agent answers with a value, and a rule in a readable workflow.yaml routes on it. landrace validate checks that every loop has a bound before anything runs. When two rules match, the item stops instead of guessing. An item stopped for a person, for this or for a failure, is a halt (Architecture).
• Local-first. Landrace runs on your machine, with your coding agent and your git credentials. There is no server to host and no database: each item's progress is re-read from the tracker and its pull requests on every pass, so after a crash Landrace recovers by reading again (Derived state).
• Workspaces. A project's workspace is its .landrace/ folder: its workflows live there and can be reviewed like code. One landrace start runs several side by side (this repository runs two: full-cycle, which starts with a written spec, and fastlane, for small changes), and each item is worked by one of them only: an item two would take stops for a person (Several workflows).
• The engine knows no vendor. GitHub, GitLab, Jira, Notion, Slack, Claude Code and Codex are integrations, not part of the engine. You can add your own on the integration kit: see Writing an integration.
• MCP. Drive Landrace from your coding agent's chat, over the Model Context Protocol: see MCP.
• The board. A local web page that sorts items into lanes, with the ones that need you first. From it you reply, retry a failed agent run, or start pairing (The board).
• Pairing. Work a step together with the agent in your own terminal instead of letting it run alone: write the spec with it, or build with it. Landrace holds the step for you, and when you finish, the work is handed in as yours. In full-cycle, a spec written together needs no separate approval. Start it from the board or with landrace_pair over MCP (the operator tools). It works with Claude Code and Codex; Codex can only carry on a step its agent has already run.
• A person at the gates you choose, or none. Approve a spec, merge a pull request, or let fastlane merge by itself (The shipped workflows). Browser or Slack notifications say when an item needs you.
• Dependencies. In the shipped workflows, an item waits before it builds until the items blocking it are done (Waiting on blockers).
• It learns from friction. In the shipped workflows, a retro agent writes the lessons from an item that needed corrections into the agents' prompts and docs, and a person reads them before they merge (The retro).
• Security. Before an agent that can act runs, its prompt is screened for injected instructions. An agent that may change files runs its shell commands in a sandbox, and the tracker's token never reaches an agent. Fastlane never merges a change to a protected path, a file that changes how Landrace itself runs: it waits for a person (Security).
• OpenTelemetry. Every engine event can be exported to your collector. It is off by default (Telemetry).

What it does

Landrace watches your issue tracker. Each issue it works on is an item, and a workflow moves the item through stages: spec, build, review, fix, CI and merge. At some stages a coding agent, such as Claude Code or Codex, does one piece of work, called a step. It writes the spec, the code, the review or the fix.

The agent never chooses what happens next. It answers with a value, and a rule in the workflow routes on that value. A deterministic state machine decides every step, and a person decides at the gates you choose. This repository ships two workflows: full-cycle starts with a written spec, and fastlane, for small changes, starts at the build.

stateDiagram-v2
    direction LR
    state "A person approves the spec" as approve
    state "Merge: a person, or fastlane by itself" as merge
    [*] --> spec: full-cycle
    [*] --> build: fastlane
    spec --> approve
    approve --> build
    build --> review
    review --> fix: findings
    fix --> review
    review --> merge: clean, full-cycle
    review --> ci: clean, fastlane
    ci --> build: checks failed
    ci --> merge: checks passed
    merge --> [*]

Quick start

You need Node 22 or newer, a GitHub repository and a classic token with the repo scope, and Claude Code or Codex installed.

In your repository's root:

npm install -g landrace
landrace init main

init writes .landrace/: a commented landrace.yaml, and a workflow named main that takes issues labelled lr:main. It also adds .landrace/.env to .gitignore. Before you start it, connect it to GitHub and Claude Code.

1. Create .landrace/hooks/project.ts. A hook is a TypeScript module that connects Landrace to a tracker, a forge (where pull requests live) or a coding agent:

   import { compose } from "landrace/kit";
   import { GitHubForge, GitHubIssues, GitHubPages } from "landrace/integrations/github";
   import { Claude } from "landrace/integrations/claude";
   
   export const { preflight, source, operator, pre, post, spec } = compose({
     tracker: new GitHubIssues(), forge: new GitHubForge({ closingRefs: true }), docs: new GitHubPages(),
   });
   export const claude = new Claude();
   

2. Replace .landrace/landrace.yaml with this, naming your own repository:

   version: 1
   agent:
     adapter: claude
   tracker:
     repo: your-org/your-repo   # your GitHub repository, as owner/name
   secrets:
     githubToken: $GITHUB_TOKEN
   log:
     redact: [githubToken]
   

3. In .landrace/workflows/main/workflow.yaml, uncomment hooks: and list ../../hooks/project.ts under it.

4. Put your token in .landrace/.env, as GITHUB_TOKEN= followed by the token.

Using Codex instead? Its hook and settings are in Integrations. Then start Landrace:

landrace start

start checks the token's permissions, then opens the board at http://127.0.0.1:4545/ in your browser. Every 60 seconds it runs a tick: one pass over the tracker's issues.

To give it work, label an issue lr:main. On the next tick the issue enters the todo stage, and the board lists it under Waiting. The workflow init wrote runs no agent yet, so the issue stays there. To run one, give todo a step, as Workflows shows. A step that changes files reaches only the hosts listed under agent.sandbox.hosts, so list your forge and package registry there: see A write step's sandbox. Each step is a paid agent run, and a cap in the workflow bounds how many times each step runs.

The two workflows

Both shipped workflows are examples. Their hooks, step prompts and protected paths are this repository's own, so a copy needs them changed. Each open item is claimed by exactly one workflow, decided by its labels.

Both also stop for a person at a halt: a step whose output was broken, a push the forge refused, or a blocker that was dropped. Fastlane's protected paths are .landrace/, CI, pnpm's dependency files and the agents' instructions. Every stage, cap and protected path is in Workflows.

The board

landrace start serves the board on 127.0.0.1 only. It shows:

• Needs You, the home page: every item waiting for a person, across all workflows, most urgent first.
• A page per workflow, with its items in lanes: Needs you, Agent running, Held elsewhere, Waiting, Not admitted and Done.
• An item's panel: its stage, its pull requests and spec, its conversation with Landrace, and its relationships to other items. From 640 px up the panel is always open on the right, so the board never shifts; with nothing selected it says "Select an item to see its details".

From the board, a person can reply on an item, ask the step that last ran a question, then hand the item back to its workflow. They can retry a failed step, or send an item back to an earlier step. They can also pair on a step. Browser notifications say when an item needs you.

A Claude Code plugin shows the same board in a pane beside the chat: see The board in a Claude Code pane.

MCP

landrace mcp is Landrace's operator server: an MCP server over stdio, whose tools read and drive items as the board does, and also open and edit them. Claude Code, Codex or Cursor use it from a chat, where you type requests such as:

• "What needs me?"
• "File a fastlane item to fix the bell."
• "Approve #71's spec."
• "Send #65 back to build with this note."
• "Make #59 wait for #56."

The agent answers them with tools such as landrace_waiting, landrace_create_item, landrace_reply, landrace_goto, and landrace_update_item, whose relate field links one item to another. Every tool is in the operator tools. How this repository connects Claude Code and Codex is in Connecting an editor.

The Chat entries in an item's ⋯ menu on the board open a chat about it over this server, with the prompt filled in. A step allowed to create sub-items gets the engine's own server instead, a separate one bound to its item, with exactly one tool, landrace_create_child: see Workflows.

Dependencies

"Blocked by" on the tracker holds an item until its blockers are done. It is a relationship, a typed link from one item to another: GitHub's issue dependencies, or Jira's "Blocks" links. Both workflows hold a blocked item before it builds, and the board shows it under Waiting with a note such as waiting on #55, #56, #57. A blocker that was dropped, cannot be read, or sits on a cycle sends the item to a person instead. See Waiting on blockers.

How it works

flowchart LR
    tracker[("Tracker")] -->|items, labels, comments| engine["Landrace engine"]
    engine -->|a step's prompt| agent["Coding agent"]
    agent -->|commits on the item's branch| forge[("Forge")]
    forge -->|pull requests, reviews, checks| engine

• The pure core decides. From one snapshot of an item, it finds the item's stage and what happens next. It does no I/O, reads no clock and draws no random numbers.
• Hooks talk to the world. Hooks read and write the tracker and the forge, and run the coding agent. The engine itself names no vendor.
• Effects belong to stages. An effect is a write, such as a label, a comment or a merge. A stage lists the effects of being in it.
• Each effect knows when it is done. A pass that runs twice writes each effect once, so a crash mid-pass is safe.
• State is derived. An item's stage is a label, and its rounds are a count of Landrace's own comments, read again on every pass.
• Read more in Architecture: the layers, the loop and the item graph.

Integrations

Landrace develops itself on GitHub, Claude Code and Slack. The others pass their tests offline, but nobody has checked them against the live service yet.

GitHub, GitLab, Jira and Notion each have a script that checks the integration against a live account. To connect something else, see Writing an integration.

Safety

• Write steps run sandboxed. A step that may change files runs its shell commands in the coding agent's OS sandbox. Under Claude Code, those commands write only to the step's worktree and the repository's git directory, and reach only the hosts you list. In-process tools such as WebFetch follow Claude Code's own permission rules instead. Codex's sandbox keeps less: see Integrations.
• The agent never holds the tracker's token. Landrace makes every tracker and forge write itself: pull requests, comments and labels. A write step pushes its own branch with your git credentials, so protect your default branch on the forge before you run one.
• Untrusted text cannot forge control state. Everything Landrace writes ends in a hidden marker, and only the last marker in a comment counts. Landrace escapes text it did not write, so neither an agent nor a commenter can fake a Landrace record.
• Prompts are screened. Before any step that can act, a separate agent run with no tools checks the prompt for injected instructions.
• Fastlane never merges a protected path without a person. It merges only the commit the review read, when no check on it has failed or is still running. A commit with no checks counts as passing, so require status checks on your default branch.
• What runs on your machine: Landrace, as one process; the coding agent's CLI, in a git worktree per item under your temporary folder; and the board, on 127.0.0.1. Landrace reaches the outside only through your hooks, through telemetry when you turn it on, and through npm's registry, which start asks whether a newer version is out (turned off with LANDRACE_NO_UPDATE_CHECK=1).

Documentation

Contributing

Contributions are welcome. CONTRIBUTING.md says what a change needs to be merged: the gate, tests first, and the boundaries the code keeps.

License

Landrace is released under the MIT License.