Skip to content

Configuration Guide

bip uses a global config file and per-repository config files, all in YAML format.

Configuration Files

  1. Global config file - ~/.config/bip/config.yml
  2. Per-repository config - .bipartite/config.yml (for repo-specific settings)

Global Configuration

The global config file stores settings that apply across all bip commands, regardless of which repository you're in.

Location

The config file follows the XDG Base Directory specification: - Default: ~/.config/bip/config.yml - Custom: Set XDG_CONFIG_HOME to change the base directory

Creating the Config File

mkdir -p ~/.config/bip
cat > ~/.config/bip/config.yml << 'EOF'
nexus_path: ~/re/nexus
EOF

Keep the tokens out of config.yml: agents read it routinely, so a secret in it ends up in a session transcript. Put them in ~/.config/bip/secrets.env beside it, which bip reads itself, so they never enter a shell's environment:

( umask 077; cat > ~/.config/bip/secrets.env << 'EOF'
BIP_ASTA_API_KEY=your-asta-key
BIP_GITHUB_TOKEN=ghp_your-github-token
BIP_SLACK_TOKEN=xoxb-your-slack-bot-token
BIP_SLACK_WEBHOOK_CHANNEL_NAME=https://hooks.slack.com/services/...
EOF
)

Each token is looked up as an environment variable first, then under the same name in secrets.env, then in config.yml. Lines may start with export and values may be quoted. Slack webhook URLs are secrets too: anyone holding one can post to the channel. Each goes in secrets.env as BIP_SLACK_WEBHOOK_<CHANNEL>, where <CHANNEL> is the channel name upper-cased with every character other than a letter or digit replaced by _ (nonparam-f-matrix → BIP_SLACK_WEBHOOK_NONPARAM_F_MATRIX).

Configuration Options

Field Description
nexus_path Default bipartite repository path. Allows running bip commands from anywhere.
asta_api_key AI2 API key (register here), used for both the ASTA MCP API and the Semantic Scholar Graph API — AI2 issues one key for both. Prefer BIP_ASTA_API_KEY in secrets.env; looked up as BIP_ASTA_API_KEY, then ASTA_API_KEY.
github_token GitHub personal access token (setup guide). Prefer BIP_GITHUB_TOKEN in secrets.env; looked up as BIP_GITHUB_TOKEN, GITHUB_TOKEN, then GH_TOKEN.
slack_bot_token Slack bot token for reading channel history. Prefer BIP_SLACK_TOKEN in secrets.env; looked up as BIP_SLACK_TOKEN, then SLACK_BOT_TOKEN.
slack_webhooks Slack webhook URLs keyed by channel name. Prefer BIP_SLACK_WEBHOOK_<CHANNEL> in secrets.env; looked up as BIP_SLACK_WEBHOOK_<CHANNEL>, then SLACK_WEBHOOK_<CHANNEL>.
spawn_agent Default agent runner for bip spawn (claude or agy, default: claude). Also accepts env var: BIP_SPAWN_AGENT.
ntfy_topic ntfy.sh topic bip page pushes to; subscribe to it in the ntfy app. Also accepts env var: BIP_NTFY_TOPIC.

Note: For the three tokens and the webhooks, each name is looked up in the environment, then in secrets.env, and only then is the config.yml field used. For other fields, an environment variable overrides the field. Empty values are treated as unset.

Example: Running bip from Anywhere

With nexus_path configured, you can run bip commands from any directory:

# Without config - must be in a bipartite repo
cd ~/re/nexus
bip search "phylogenetics"

# With global config - works from anywhere
cd /tmp
bip search "phylogenetics"  # Uses nexus_path from config

GitHub Authentication

bip uses GitHub through two independent authentication paths. You need both configured for full functionality.

Step 1: Authenticate the gh CLI

Most bip commands (checkin, board, spawn, digest) call the GitHub API through the gh CLI. You must authenticate it first:

gh auth login

Follow the interactive prompts. When asked about scopes, the defaults (repo, read:org) cover most bip features. However, for project board commands (bip board list/add/move/remove), you also need the project scope:

gh auth refresh --scopes project

Verify your authentication:

gh auth status

Step 2: Give bip a Personal Access Token

bip's Go HTTP client uses a separate token of its own for repository metadata fetching and higher rate limits. To create one:

  1. Go to github.com/settings/tokens (Profile photo → Settings → Developer settings → Personal access tokens)
  2. Choose Fine-grained tokens (recommended) or Tokens (classic)

Fine-grained tokens are more secure because you scope them to specific repositories and permissions:

  1. Click Generate new token
  2. Set a descriptive name (e.g., "bip CLI")
  3. Set expiration (90 days or custom)
  4. Under Repository access, choose "All repositories" or select specific repos you track with bip
  5. Under Permissions → Repository permissions, enable:
  6. Issues: Read-only
  7. Pull requests: Read-only
  8. Metadata: Read-only (automatically selected)
  9. Under Permissions → Organization permissions (if you use org project boards):
  10. Projects: Read and write
  11. Click Generate token and copy the value

Classic token

If you prefer classic tokens or need compatibility with older GitHub Enterprise versions:

  1. Click Generate new token (classic)
  2. Set a descriptive name and expiration
  3. Select these scopes:
  4. repo — Read access to repositories (issues, PRs, comments)
  5. read:org — Read organization membership (needed for org project boards)
  6. project — Read/write GitHub project boards
  7. Click Generate token and copy the value

Supply the token via an environment variable

Set BIP_GITHUB_TOKEN in ~/.config/bip/secrets.env (see Creating the Config File), or in the environment from a secrets manager like 1Password op run. bip consults, in order:

  1. BIP_GITHUB_TOKEN (recommended)
  2. GITHUB_TOKEN
  3. GH_TOKEN
  4. the same names in ~/.config/bip/secrets.env
  5. github_token in ~/.config/bip/config.yml

The BIP_-prefixed name is recommended when a globally-exported GITHUB_TOKEN (e.g., for the gh CLI) might have different scopes than what you want bip to use. Empty env vars are treated as unset and fall through to the next source.

# Example: pull from 1Password CLI for a single command
op run --env-file=<(echo 'BIP_GITHUB_TOKEN=op://Private/bip-github-pat/token') -- bip repo refresh

Which commands need what

Command Auth method What it does
bip checkin gh CLI Fetches issues, PRs, comments across repos
bip board list/add/move/remove gh CLI Reads/writes GitHub project boards (needs project scope)
bip spawn gh CLI Fetches issue/PR details for tmux sessions
bip digest gh CLI Generates activity summaries
bip repo add/refresh BIP_GITHUB_TOKEN Fetches repository metadata

Troubleshooting

"gh: not logged in" — Run gh auth login.

403 on project board commands — You need the project scope: gh auth refresh --scopes project.

Rate limiting on bip repo commands — Add github_token to your config file. Without a token, these requests are unauthenticated and limited to 60/hour.

Per-Repository Configuration

Each bipartite repository has its own config file at .bipartite/config.yml. This file stores repository-specific settings that don't belong in the global config.

Example

pdf_root: ~/papers
pdf_reader: skim
papers_repo: ~/re/bip-papers

Options

Field Description
pdf_root Directory containing PDF files
pdf_reader PDF reader to use: system, skim, zathura, evince, okular
papers_repo Path to a linked papers repository

Security Considerations

  • The config file may contain API keys - ensure proper file permissions: 
    chmod 600 ~/.config/bip/config.yml
  • Never commit API keys to version control

Troubleshooting

"No bipartite repository found"

If you see this message, bip couldn't find a repository. The message includes setup instructions:

No bipartite repository found.

Tip: Create ~/.config/bip/config.yml to set a default nexus:
  mkdir -p ~/.config/bip
  echo 'nexus_path: ~/re/nexus' > ~/.config/bip/config.yml

Checking Current Configuration

To verify your config is being read correctly:

# Show the non-secret settings bip read
bip config

# Test by running a simple command
bip --version

Path Expansion

The ~ character is automatically expanded to your home directory in the config file:

nexus_path: ~/re/nexus

This is equivalent to /Users/yourname/re/nexus (or /home/yourname/re/nexus on Linux).