bipartite

Agentic hacking like a PI.

For motivation and a walkthrough of the workflow, see the blog post: Bipartite: manuscript-driven development with a team of agents.

Computational PIs have always worked at a high level: directing teams of researchers, framing problems, choosing which experiments are worth running, and weaving the results into papers. Bipartite is a platform for bringing that workflow into the agentic age — a bip CLI and a library of Claude Code skills that coordinate teams of agents across GitHub issues, code repositories, manuscripts, and the literature.

The workflow runs as two coupled loops, ideas and experiments, with GitHub as the shared transport layer. On the ideas side, manuscript sessions surface new results, situate them in the literature, and turn them into well-scoped issues. On the experiments side, those issues are picked up by autonomous workers in dedicated clones, implemented, reviewed, and landed — surfacing fresh results back for discussion. Two human touchpoints anchor the otherwise-autonomous flow: high-level discussion of new findings on the ideas side, and pre-merge review on the experiments side.

For a PI, the paper is the unit that ties a team's work together. Manuscript sessions (/bip-ms) operate at that level: they track EPIC issues across code repositories and react when new results arrive. High-level discussion of findings, grounded in the literature via /bip-lit, becomes new issues, which are validated against project conventions before being filed.

Key skills: /bip-ms, /bip-lit, /bip-issue-file, /bip-issue-check, /bip-issue-next, /bip-ms-sweep (pre-submission polish), /bip-ms-math (revise a manuscript's mathematics in reviewable commits), /bip-lit-import (Paperpile import)

The experiments side is the EPIC orchestration system — split across two roles. A topic-scoped /bip-epic session tracks program strategy, triages issues/PRs, and flags dependency/collision conflicts between them; a topic-agnostic /bip-conductor session owns the clone pool, spawns workers in dedicated tmux windows, and runs mechanical checks (staleness, occupancy) neither role could catch alone. The two coordinate over SendMessage and a shared .spawn-prompts/ directory. Workers implement, test, and create PRs autonomously. Two subagents keep the loop honest: an issue-lead evaluates progress from file-based state and escalates only when human judgment is needed, and a surprising-conclusion-skeptic interrogates strong or negative claims before they propagate. Quality gates and PR landing close the loop, with follow-up issues flowing back to the ideas side.

Key skills: /bip-epic, /bip-conductor, /bip-conductor-spawn, /bip-pr-review, /bip-pr-land, /bip-epic-check, /bip-conductor-prepare-reboot and /bip-conductor-recover (host reboots)

The Agent Roles guide names the session roles (conductor, epic, manuscript, staff, worker) and what each owns. The Issue Lifecycle guide gives the order in which to run the issue and PR skills, from draft to landed PR.

Cross-cutting tools that span both sides of the workflow: a conductor's GitHub inbox, Slack integration, and server resource scouting via SSH.

Key skills: /bip-inbox, /bip-scout

Standalone: /bip-helper (a long-lived background session for side work), /bip-recap (what you did in the last two weeks), /bip-decay-audit (whole-repo decay check), /bip-marimo (marimo notebooks), /bip-tuckin and /bip-continue (carry a session across a context reset)

The library backing /bip-lit is an agent-first reference manager with JSON output, a CLI interface, git-backed JSONL storage, and search via Semantic Scholar and Asta. Because the storage format is JSONL, your library is mergeable across collaborators using standard git workflows.

Guide: Reference Management

You can adopt bipartite in three tiers: one Claude session with the skills-starter skills, then several named sessions that message each other, then a tmux fleet. Where to Start says what each tier needs.

This installs the bip CLI plus Claude Code agents and skills:

git clone https://github.com/matsen/bipartite
cd bipartite
make install

Prerequisites:

• Go 1.24+
• Claude Code

Verify with bip --help.

If you just want the bip CLI without agents/skills:

go install github.com/matsen/bipartite/cmd/bip@latest

Note: This installs to $GOBIN if set, otherwise $HOME/go/bin. Ensure the appropriate directory is in your PATH.

1. Create your private nexus — the repository that stores your paper library, workflow config, and project context. Click "Use this template" on nexus-template, then clone:

git clone https://github.com/YOUR_USERNAME/nexus ~/re/nexus

2. Point bip to your nexus (minimal config to get started):

mkdir -p ~/.config/bip
echo 'nexus_path: ~/re/nexus' > ~/.config/bip/config.yml

3. Build the index and try it out:

bip rebuild
bip search "phylogenetics" --human
bip s2 add DOI:10.1038/s41586-021-03819-2

See the Getting Started guide for full setup instructions.

• Where to Start: the three tiers, from one session to a fleet
• Getting Started: full setup
• Configuration: every config option and token
• Agent Roles: the session roles and what each owns
• Issue Lifecycle: which skill to run at each step, from draft issue to landed PR
• Workflow Coordination: check-ins, digests, Slack, bip spawn
• Reference Management: the paper library behind /bip-lit
• Projects, Repos, and Stores
• Worktree Layout: opt-in per-issue git worktrees
• Continuation Prompt: /bip-tuckin and /bip-continue across context resets
• Server Scout
• How It Works: the nexus, the CLI, and Claude Code

Every skill lives in skills/; the description: line at the top of each SKILL.md says what it does.

Set nexus_path in ~/.config/bip/config.yml:

nexus_path: ~/re/nexus

For full functionality, put API keys (ASTA/Semantic Scholar, GitHub, Slack) in ~/.config/bip/secrets.env (mode 600), not in config.yml, which agents read routinely:

BIP_ASTA_API_KEY=your-key
BIP_GITHUB_TOKEN=ghp_...
BIP_SLACK_TOKEN=xoxb-...

asta_api_key covers both the ASTA MCP API and the Semantic Scholar Graph API — AI2 issues a single key for both.

bip looks each token up in the environment, then under the same names in secrets.env, then in the matching config.yml field (asta_api_key, github_token, slack_bot_token):

The BIP_-prefixed names are recommended when a globally-exported GITHUB_TOKEN (e.g. for the gh CLI) might have different scopes than what you want bip to use.

See the Configuration Guide for all options.

To opt into per-issue git worktrees for bip spawn (instead of one shared clone per repo), see Worktree Layout.

Bipartite isn't just for people who hold the official PI title. It's for anyone who wants to work with a team of agents the way a PI works with a team of researchers — directing the science at a high level while detailed work runs across many parallel sessions.

MIT