Skip to content

Getting Started

Bipartite operates on a nexus — a directory that serves as the central hub for your paper library, server configurations, and workflow coordination. See How It Works for the full picture of how bipartite's pieces fit together.

Installation

Prerequisites

This method installs the bip CLI, Claude Code agents, and skills in one command:

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

This will:

  1. Install bip via go install (to $GOBIN if set, otherwise $HOME/go/bin)
  2. Symlink agents to ~/.claude/agents/
  3. Symlink skills to ~/.claude/skills/
  4. Symlink the statusline script to ~/.claude/statusline/

Ensure the Go bin directory is in your PATH. If you haven't configured $GOBIN, add to ~/.bashrc or ~/.zshrc:

export PATH="$HOME/go/bin:$PATH"

Then reload your shell (source ~/.bashrc or source ~/.zshrc).

Enable the Claude Code status line. Add the following to ~/.claude/settings.json to display model name, working directory, git branch, and context window usage in the Claude Code status bar:

"statusLine": {
  "type": "command",
  "command": "node ~/.claude/statusline/ctx_monitor.js"
}

Verify installation:

bip --help
ls ~/.claude/agents/
ls ~/.claude/skills/

CLI-Only Installation

If you only want the bip command-line tool without Claude Code integration:

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

This installs to $GOBIN if set, otherwise $HOME/go/bin.

Add to PATH (if you haven't configured $GOBIN):

# Add to ~/.bashrc or ~/.zshrc:
export PATH="$HOME/go/bin:$PATH"

# Then reload:
source ~/.bashrc  # or source ~/.zshrc

Verify installation:

bip --help

Manual Agent/Skill Installation

If you want to manually symlink agents and skills (instead of using make install):

# Clone repository
git clone https://github.com/matsen/bipartite
cd bipartite

# Create directories
mkdir -p ~/.claude/agents
mkdir -p ~/.claude/skills

# Symlink agents
for f in agents/*.md; do
  ln -sf "$(pwd)/$f" ~/.claude/agents/$(basename "$f")
done

# Symlink skills (note: skills are in ./skills/, not ./.claude/skills/)
for d in skills/*/; do
  ln -sf "$(pwd)/$d" ~/.claude/skills/$(basename "$d")
done

Verify:

ls -l ~/.claude/agents/
ls -l ~/.claude/skills/

Creating a Nexus

The nexus-template repository provides a ready-to-use starting point with example papers and configuration templates.

  1. Go to github.com/matsen/nexus-template
  2. Click Use this template → Create a new repository
  3. Clone your new repository:
git clone https://github.com/yourusername/my-nexus
cd my-nexus
  1. Build the search index:
bip rebuild
  1. Verify it works:
bip search "phylogenetics"

Option 2: Create Manually

For an empty nexus without using the template:

mkdir my-nexus && cd my-nexus
git init
mkdir -p .bipartite
touch .bipartite/refs.jsonl
echo ".bipartite/cache/" >> .gitignore
bip rebuild

This creates the minimal structure needed to start adding papers.

What's in a Nexus?

my-nexus/
├── .bipartite/               # Tracked in git, except cache/
│   ├── refs.jsonl            # Paper references (source of truth)
│   ├── projects.jsonl        # Projects
│   ├── repos.jsonl           # Tracked repositories
│   ├── config.yml            # (optional) Local paths, API keys
│   └── cache/                # (gitignored, ephemeral)
│       └── refs.db           # SQLite FTS index
│
├── servers.yml               # (optional) Remote servers for bip scout
├── sources.yml               # (optional) GitHub repos for activity tracking
│
├── context/                  # (optional) Project context files
└── narrative/                # (optional) Generated digest output

Core Files (Source of Truth)

  • refs.jsonl — Your paper library. Each line is a JSON object with paper metadata.
  • projects.jsonl — Project definitions (see Projects, Repos, and Stores).
  • repos.jsonl — Tracked repositories.

These files are the source of truth. They're plain text, git-friendly, and designed for collaboration.

Cache Directory (Ephemeral)

The .bipartite/cache/ subdirectory contains:

  • refs.db — SQLite full-text search index

Only cache/ is gitignored — the JSONL files above it are tracked. The cache is rebuilt from those source files via bip rebuild, so you can delete it and rebuild anytime.

Configuration Files (Optional)

  • .bipartite/config.yml — Local paths (PDF root)
  • servers.yml — Remote servers for bip scout
  • sources.yml — GitHub repos and boards for bip checkin, bip digest

Adding Your First Paper

bip s2 add DOI:10.1038/s41586-021-03819-2

This fetches metadata from Semantic Scholar and appends to .bipartite/refs.jsonl.

Searching

bip search "machine learning"        # Keyword search
bip search "author:Felsenstein"      # Author search
bip search "title:phylogenetics"     # Title search

Next Steps