{"id":45738930,"url":"https://github.com/punt-labs/biff","last_synced_at":"2026-04-16T07:01:42.874Z","repository":{"id":339069076,"uuid":"1157393793","full_name":"punt-labs/biff","owner":"punt-labs","description":"Team (human+agent) coordination and communication that works across git-repositories and hosts, enabling natural language cross-repository agent coordination and problem solving.","archived":false,"fork":false,"pushed_at":"2026-04-16T04:39:53.000Z","size":3812,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-16T05:17:54.207Z","etag":null,"topics":["beta","claude-code-plugin","messaging-platform"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/punt-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-13T19:10:07.000Z","updated_at":"2026-04-16T04:39:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"82eecdb5-2163-4b00-8cdc-d11ab0fbc457","html_url":"https://github.com/punt-labs/biff","commit_stats":null,"previous_names":["punt-labs/biff"],"tags_count":52,"template":false,"template_full_name":null,"purl":"pkg:github/punt-labs/biff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punt-labs%2Fbiff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punt-labs%2Fbiff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punt-labs%2Fbiff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punt-labs%2Fbiff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/punt-labs","download_url":"https://codeload.github.com/punt-labs/biff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punt-labs%2Fbiff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31875183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beta","claude-code-plugin","messaging-platform"],"created_at":"2026-02-25T12:21:43.427Z","updated_at":"2026-04-16T07:01:42.855Z","avatar_url":"https://github.com/punt-labs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# biff\n\n\u003cimg src=\"https://raw.githubusercontent.com/punt-labs/biff/main/docs/biff.png\" alt=\"The original biff mail notification app\" width=\"116\" align=\"right\"\u003e\n\n\u003e Team communication for engineers who never leave the terminal.\n\n[![License](https://img.shields.io/github/license/punt-labs/biff)](LICENSE)\n[![CI](https://img.shields.io/github/actions/workflow/status/punt-labs/biff/test.yml?label=CI)](https://github.com/punt-labs/biff/actions/workflows/test.yml)\n[![PyPI](https://img.shields.io/pypi/v/punt-biff)](https://pypi.org/project/punt-biff/)\n[![Python](https://img.shields.io/pypi/pyversions/punt-biff)](https://pypi.org/project/punt-biff/)\n[![Working Backwards](https://img.shields.io/badge/Working_Backwards-hypothesis-lightgrey)](./prfaq.pdf)\n\nNamed after the Berkeley dog whose 1980 mail notification program was part of the same BSD family as `talk`, `wall`, `finger`, `who`, and `mesg`. Biff resurrects the Unix communication vocabulary as MCP-native slash commands inside Claude Code.\n\n**Platforms:** macOS, Linux\n\n## Quick Start\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/punt-labs/biff/2b17553/install.sh | sh\n```\n\nRestart Claude Code twice. Type `/who` to see your team.\n\n\u003cdetails\u003e\n\u003csummary\u003eManual install (if you already have uv)\u003c/summary\u003e\n\n```bash\nuv tool install punt-biff\nbiff install\nbiff doctor\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eVerify before running\u003c/summary\u003e\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/punt-labs/biff/2b17553/install.sh -o install.sh\nshasum -a 256 install.sh\ncat install.sh\nsh install.sh\n```\n\n\u003c/details\u003e\n\n## Features\n\n- **MCP-native** --- runs inside Claude Code as slash commands, no separate app\n- **Interactive REPL** --- `biff` launches a terminal client with readline, real-time notifications, and modal talk\n- **BSD vocabulary** --- `/who`, `/write`, `/talk`, `/wall` --- commands engineers already know\n- **NATS relay** --- cross-machine presence and messaging over encrypted connections\n- **Agent-first** --- agents show up in `/who` alongside humans, coordinate via `/plan` and `/write`\n- **Status bar** --- live unread count, wall broadcasts, talk messages --- wraps your existing status line\n- **Zero config** --- installs in one command, activates per-repo with `/biff y`\n\n## What It Looks Like\n\n### See who's online\n\n```text\n\u003e /who\n\n▶  NAME    TTY   IDLE  S  HOST       DIR                        PLAN\n   @kai    tty1  0:03  +  m2-mb-air  /Users/kai/code/myapp      refactoring auth module\n   @eric   tty2  1:22  +  m2-mb-air  /Users/eric/code/myapp     reviewing PR #47\n   @priya  tty1  0:00  +  priya-mbp  /Users/priya/code/myapp    writing integration tests\n```\n\n`S` is message status: `+` means accepting messages, `-` means do not disturb.\n\n### Send a message\n\n```text\n\u003e /write @kai \"auth module looks good, just one nit on the error handling\"\n\nMessage sent to @kai.\n```\n\n### Check your inbox\n\n```text\n\u003e /read\n\n▶  FROM   DATE              MESSAGE\n   kai    Sat Feb 15 14:01  hey, ready for review?\n   eric   Sat Feb 15 13:45  pushed the fix for the flaky test\n   priya  Sat Feb 15 12:30  can you look at the migration script?\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eMore examples: /finger, /plan, /last, /wall, /talk, /mesg\u003c/summary\u003e\n\n### Check what someone is working on\n\n```text\n\u003e /finger @kai\n\n▶  Login: kai                              Messages: on\n   On since Sat Feb 15 14:01 (UTC) on tty1, idle 0:03\n   Host: m2-mb-air  Dir: /Users/kai/code/myapp\n   Plan:\n    refactoring auth module\n```\n\n### Set your status\n\n```text\n\u003e /plan \"debugging the websocket reconnect logic\"\n\nPlan: debugging the websocket reconnect logic\n```\n\nBead IDs auto-expand:\n\n```text\n\u003e /plan biff-ka4\n\nPlan: biff-ka4: post-checkout hook: update plan from branch\n```\n\n### Session history\n\n```text\n\u003e /last\n\n▶  NAME    TTY   HOST       LOGIN             LOGOUT            DURATION\n   @kai    tty3  m2-mb-air  Sat Feb 22 14:01  still logged in   -\n   @kai    tty2  m2-mb-air  Sat Feb 22 11:30  Sat Feb 22 13:58  2:28\n   @eric   tty1  m2-mb-air  Sat Feb 22 09:15  Sat Feb 22 12:45  3:30\n```\n\n### Broadcast to the team\n\n```text\n\u003e /wall \"release freeze --- do not push to main\" 2h\n\nWall posted (2h): release freeze --- do not push to main\n```\n\nEvery teammate's status bar shows `WALL: release freeze` in bold red. Expires automatically.\n\n### Talk in real time\n\n```text\n\u003e /talk @kai \"can you review PR #42?\"\n\nWaiting for @kai to respond...\nConnected to @kai. Type 'end' to return.\n```\n\nBSD-style two-phase handshake: the inviter waits, the target accepts. Messages are ephemeral (NATS core pub/sub, no inbox). Either side types `end` to hang up.\n\n### Go do-not-disturb\n\n```text\n\u003e /mesg n\n\nis n\n```\n\nYour status bar shows `(n)` instead of the unread count. Messages still accumulate --- `/mesg y` or `/read` reveals them.\n\n\u003c/details\u003e\n\n## Commands\n\n| Command | Origin | Purpose |\n|---------|--------|---------|\n| `/write @user \"text\"` | BSD `write` | Send a message |\n| `/read` | BSD `from` | Check your inbox |\n| `/finger @user` | BSD `finger` | Check what someone is working on |\n| `/who` | BSD `who` | List active sessions |\n| `/last` | BSD `last` | Show session login/logout history |\n| `/plan \"text\"` | BSD `.plan` | Set your status |\n| `/tty \"name\"` | BSD `tty` | Name the current session |\n| `/talk @user \"msg\"` | BSD `talk` | Start a real-time conversation |\n| `/wall \"text\"` | BSD `wall` | Broadcast to the team |\n| `/mesg y` \\| `/mesg n` | BSD `mesg` | Control message reception |\n\n## CLI\n\nEvery slash command has a matching `biff` CLI command. The CLI works outside Claude Code --- from any terminal, SSH session, or CI script.\n\n### Interactive REPL\n\n```bash\nbiff                                       # Launch interactive REPL\n```\n\n```text\nbiff 0.15.1 — kai:tty1\nCommands: finger, last, mesg, plan, read, status, tty, wall, who, write, talk, exit\n\nkai:tty1 ▶ who\n▶  NAME    TTY   IDLE  S  HOST       DIR              PLAN\n   @kai    tty1  0:00  +  m2-mb-air  /code/myapp      debugging auth\n   @eric   tty2  1:22  +  m2-mb-air  /code/myapp      reviewing PR #47\nkai:tty1 ▶ talk @eric\nWaiting for @eric:tty2 to respond... (type 'end' to cancel)\nConnected to @eric:tty2. Type 'end' to return to REPL.\n\nkai:tty1 ▶ can you look at the auth fix?\neric:tty2 ▶ on it now\nkai:tty1 ▶ end\nTalk with @eric:tty2 ended.\nkai:tty1 ▶ exit\n```\n\nThe REPL provides a proper session lifecycle (login/logout events, heartbeat, KV presence), readline (history, tab completion), and real-time notifications (wall broadcasts and message alerts appear while you're idle at the prompt). `biff` with no args is the primary mode; `biff who` is a shortcut for a one-command session.\n\n### Product commands\n\n```bash\nbiff who                                   # List active sessions\nbiff finger @kai                           # Check what someone is working on\nbiff write @kai \"review the PR\"            # Send a message\nbiff read                                  # Check your inbox\nbiff plan \"debugging websocket reconnect\"  # Set your status\nbiff last                                  # Session login/logout history\nbiff last @kai --count 10                  # Filter by user, limit results\nbiff wall \"deploy freeze\" --duration 2h    # Broadcast to the team\nbiff wall                                  # Read active wall\nbiff wall --clear                          # Remove active wall\nbiff mesg off                              # Go do-not-disturb\nbiff mesg on                               # Accept messages again\nbiff tty dev                               # Name this session \"dev\"\nbiff status                                # Connection state + unread count\nbiff talk @kai \"can you review?\"           # Real-time conversation\n```\n\n### Admin commands\n\n```bash\nbiff install                # Install plugin via marketplace\nbiff enable                 # Activate biff in current repo (creates .biff)\nbiff disable                # Deactivate biff in current repo\nbiff doctor                 # Check installation health\nbiff mcp                    # Start MCP server (stdio, called by plugin)\nbiff serve                  # Start MCP server (HTTP)\nbiff uninstall              # Remove plugin and clean up\nbiff version                # Print version\n```\n\n### Global flags\n\n```bash\nbiff --json who             # JSON array of sessions\nbiff --json status          # JSON object with version, unread, wall\nbiff --json read            # JSON array of messages\nbiff --verbose who          # Debug logging to stderr\nbiff --quiet write @kai \"msg\"  # Suppress non-JSON output\nbiff --user github-actions wall \"CI failed\"  # Identity override for bots\n```\n\nGlobal flags (`--json`, `--verbose`, `--quiet`, `--user`) go before the subcommand.\n\n### Library API\n\nCommands are also importable as pure async functions:\n\n```python\nfrom biff import commands, CliContext, CommandResult\nfrom biff.relay import LocalRelay\n\nrelay = LocalRelay(data_dir)\nctx = CliContext(relay=relay, config=config, session_key=\"kai:abc123\", user=\"kai\", tty=\"abc123\")\n\nresult: CommandResult = await commands.who(ctx)\nprint(result.text)       # Human-readable output\nprint(result.json_data)  # JSON-serializable data\nprint(result.error)      # True if command failed\n```\n\nAll 10 product commands (`who`, `finger`, `write`, `read`, `plan`, `last`, `wall`, `mesg`, `tty`, `status`) follow this pattern. See the [design log](DESIGN.md#des-022-library-api--command-extraction-via-humble-object-pattern) for architecture details.\n\n## Setup\n\nBiff requires a git repo and a GitHub identity. Your username and display name are resolved automatically from `gh auth` --- no manual configuration needed.\n\n### Create a `.biff` file\n\nCommit a `.biff` file in your repo root (TOML format):\n\n```toml\n[team]\nmembers = [\"kai\", \"eric\", \"priya\"]\n\n[relay]\nurl = \"tls://connect.ngs.global\"\n\n[peers]\norgs = [\"my-org\"]           # auto-discover repos in this GitHub org\nrepos = [\"my-org/other-repo\"]  # explicit peers (always visible)\n```\n\nBiff ships with a shared demo relay so your team can start immediately. When you're ready for your own relay, see [relay configuration](docs/INSTALLING.md#relay-configuration).\n\nThe `[peers]` section enables cross-repo commands (`/who`, `/write`, `/finger`). `orgs` auto-discovers repos with active sessions; `repos` lists peers that are always visible. Both are optional.\n\n`biff install` registers the MCP server, installs slash commands, and enables the plugin. `biff enable` activates biff in the current repo and deploys git hooks. Run `biff doctor` to verify everything is wired up. See [Installing](docs/INSTALLING.md) for the full guide.\n\n## Status Bar\n\nBiff appends to your existing Claude Code status line --- it never replaces it:\n\n```text\nLine 1: your-existing-status | kai:tty1(3)\nLine 2: ▶ WALL: release freeze until 5pm\n```\n\nThree states: `kai:tty1(0)` when caught up, **`kai:tty1(3)`** (bold yellow) with unreads, `kai:tty1(n)` when messages are off. Line 2 shows active `/talk` messages (bold yellow), wall broadcasts (bold red), or an idle marker.\n\n## Agents Welcome\n\nBecause biff speaks MCP, it does not distinguish between human and agent sessions. An autonomous coding agent can `/plan` what it's working on, `/write` a human when it needs a decision, and show up in `/who` alongside everyone else.\n\nBiff coordinates hybrid teams across two planes:\n\n- **Logical plane (cross-machine):** `/plan` shows the task each agent is working on. `/who` shows all plans across all machines. This prevents duplicate work.\n- **Physical plane (same-machine):** `/who` shows host and directory per session. When two agents share the same machine and directory, they coordinate via `/write` and create git worktrees to work in isolation.\n\nSee [Agent Workflow](docs/AGENT_WORKFLOW.md) for patterns and examples.\n\n## Vision\n\nBiff assumes the terminal is where you're already working — so that's where your team communication should be. Every command implies intent. There are no channels to monitor, no threads to catch up on, no emoji reactions to parse. Communication is pull-based: you decide when to engage.\n\n## Roadmap\n\n### Shipped\n\n- Presence: `/who`, `/finger`, `/plan`, `/tty`, `/last`\n- Messaging: `/write`, `/read`, `/mesg`\n- Broadcast: `/wall` with duration-based expiry\n- Real-time: `/talk` with two-phase handshake and mutual hangup\n- NATS relay for cross-machine communication\n- Per-project activation (`/biff y`) with lazy connection management\n- Status bar with live unread count, wall, and talk display\n- Workflow hooks: plan auto-expand, session lifecycle, git integration\n- CLI parity: every MCP tool available as `biff \u003ccommand\u003e` with `--json` output\n- Interactive REPL: `biff` with readline, real-time notifications, modal talk\n- Library API: pure async functions for programmatic use and testing\n- Notification deferral: ≤2s latency for wall and talk in all states (active and napping)\n- Formal verification: Z specifications for talk and REPL, ProB model-checked\n\n### Next\n\n| Phase | What Ships |\n|-------|-----------|\n| **Security** | E2E encryption (NaCl/libsodium), GitHub identity and auth, per-repo NATS credentials |\n| **Real-time** | `/pair` for session sharing with explicit consent |\n| **Hosted relay** | Managed service with admin controls, audit logs, team isolation |\n\n## Documentation\n\n[Installing](docs/INSTALLING.md) |\n[Agent Workflow](docs/AGENT_WORKFLOW.md) |\n[Claude Setup](docs/CLAUDE_SETUP.md) |\n[FAQ](docs/FAQ.md) |\n[Troubleshooting](docs/TROUBLESHOOTING.md)\n\n[Design Log](DESIGN.md) |\n[Installer Design](DESIGN-INSTALLER.md) |\n[Testing Guide](TESTING.md) |\n[Changelog](CHANGELOG.md) |\n[Contributing](CONTRIBUTING.md)\n\n## Development\n\n```bash\nuv sync --extra dev        # Install dependencies\nmake check                 # Run all quality gates (lint, type, test)\nmake test                  # Tests only (unit + integration)\nmake lint                  # Lint and format check\nmake format                # Auto-format code\nmake help                  # List all targets\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpunt-labs%2Fbiff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpunt-labs%2Fbiff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpunt-labs%2Fbiff/lists"}