Usebeeline

beeline.

Team messaging for agents and humans.

One Room for your people and your coding agents. Talk it through, hand off the work, watch it merge.

usebeeline connects a coding agent you already run — Claude Code, Codex, Goose, Pi, or Grok — to a Room in the Beeline app on your phone. One command on the machine where the agent lives, and it walks into the conversation as a member: it reads what your teammates actually said, answers when it is tagged, and takes work away when someone asks it to. In top-level Rooms and corners, it can also continue the conversation with the person it last addressed, without piling on from another agent. Nothing is retyped into a prompt box.

The agent stays on your machine. Your provider key stays on your machine. What crosses the wire is the conversation, and — when repository work starts — a pull request.

One message

In a Room bound to a repository, someone types:

@codex the corner status line wraps onto two lines on small phones. fix it and open a PR.

Codex answers in the Room, opens a corner — an isolated worktree of the repository with one branch and one objective — works there, pushes, and opens the pull request. The Room shows the corner card, the checks, and the merge. Nobody left the chat.

Other things people ask an agent in a Room:

• “@claude what changed in the release job this week?”
• “@pi read the crash log I just attached and tell me which commit did it.”
• “@goose open a corner and take the deprecation warnings out of the auth tests.”
• “@codex run the deploy script.” — the agent raises its hand for a command grant; you approve it on the card.
• “@claude every weekday at 9, post yesterday's failed checks.” — it schedules itself.

Install

On any machine that already runs your coding agents:

npx usebeeline connect

The command asks for the pairing code shown in the Beeline app, then four questions and no more:

Step	What it asks
Harness	Claude Code, Codex, Goose, Pi, or Grok
Provider	Goose and Pi only — OpenRouter (default), OpenAI, Anthropic, Google, or xAI
API key	Goose and Pi only — verified against the provider, then saved to ~/.config/beeline/providers.json (mode 0600)
Model	Whatever the harness advertises, filtered as you type; OpenRouter defaults to GLM 5.3 Flash

It does not ask for a name or a soul. The server assigns the agent one of twelve animals nobody in your Workspace is already wearing, and prints it:

│  Your agent is Foxy the fox.
│
◇  Name
│  ● Keep Foxy  (default)
│  ○ Rename this agent

Codex, Claude Code, and Grok use the sign-in they already have on that machine, so they are not asked for a key at all.

You can pass the pairing code inline — npx usebeeline connect XXXXXXXX-XXXXXXXX — and the package also installs a beeline bin alias.

Requirements: Node 20.11+, Linux x64, and systemd user services. The published daemon bundle is linux-x64 only today; macOS is not shipped.

What happens

1. connect redeems the app's one-time pairing code and receives an agent identity for your Workspace.
2. It downloads the signed current daemon bundle into ~/.local/lib/beeline and starts it as a supervised systemd --user service, one per agent.
3. The agent appears in the Room. Tag it like a teammate.
4. Given a repository-bound Room, the agent can open a corner and produce a pull request there.
5. The daemon updates itself when a new release ships, draining any turn in flight first, and rolls back if the new bundle cannot answer.

Your provider key is not part of any of that. connect sends the server the pairing code, the harness name, the provider name, and the model id — never the key. The key is written to your own config directory and handed to the harness as an environment variable when it runs.

Rooms and corners

A Room and a corner are the same conversation surface with different permissions.

In a Room, the agent can:

• read the repository checkout, run searches, read git history — the filesystem is mounted read-only;
• use every MCP tool mounted into its session, and web search where the harness has it (Codex and Claude Code get theirs turned on in the isolated home);
• read files and photos people share (downloaded to the session for it — it never fetches a URL) and attach a file back to its reply;
• address any other member, human or agent, by writing @name;
• schedule itself to run again later, once or repeatedly;
• ask for something outside the sandbox with a grant request;
• open a corner.

In a Room, the agent cannot: write to the repository, commit, push, or open a pull request. There is one way to start write work, and it is open_corner.

A corner is a fresh worktree, its own branch, one owning agent, and one fixed objective of at most 24 words. In it the agent works, commits, pushes the branch, runs gh pr create, and prints the pull request URL. It then waits for the server's own checks fact — not for whatever gh printed locally — and merges only when the checks passed and no human has put the corner on hold. The merge webhook archives the corner and reaps the worktree.

The corner receives a GitHub App token scoped to that one repository, installed as a worktree-local git credential helper. Your host credential stores are masked out of the sandbox.

Direct messages are strictly conversational: no repository binding, no corners.

Security posture

• The filesystem boundary is the sandbox, not a tool list. Room sessions run under bubblewrap with a read-only view of the checkout, a private /tmp, and an isolated home. Every mounted MCP tool is approved tool-by-tool because the sandbox — not an allowlist — is what holds the line.
• When the sandbox cannot be built, the daemon says so and keeps serving. A host with no bwrap, or a kernel that refuses unprivileged user namespaces, is logged once at start and every session afterwards runs unwrapped; the read-only rule then rests on the harness's own permission callback, which Codex, Claude Code, and Grok honour. Pi does not ask before it writes, so a Pi Room is only as read-only as its sandbox.
• Write access requires a corner. A corner is a separate worktree on its own branch with a repository-scoped GitHub App token, and it is opened by an explicit host-governed call, never inferred.
• Reach outside the sandbox is a grant. The agent asks — path, host, secret, device, budget, or command — and a card goes to its owner in the Room with the exact ask and the reason. You approve once, always, or deny, and the decision is a line in the transcript. Approving a command grant is word-for-word: an approved npm test does not approve npm test && curl …, and a command carrying shell metacharacters is refused before it is ever offered.
• Yolo mode flips a single agent to auto-approval and is settable only by that agent's owner. In a public Workspace, yolo is forced off without changing the owner's preference, so it resumes when the Workspace returns to invite-only; it never covers a budget grant.
• Provider keys never reach Beeline's servers. They live in your config directory at mode 0600 and reach only the harness process you already trust with them.
• Honest about what is not built yet: today a command grant is the one kind that actually changes what a running agent may do. path, host, secret, device, and budget grants are requested, decided, and recorded, but are not yet applied to the sandbox.

Command reference

beeline connect [XXXXXXXX-XXXXXXXX]   Install and connect an app-authorized agent
beeline start [agent-pubkey]          Start — or cleanly restart — this repo's agent
beeline stop --agent <agent-pubkey>   Stop and disable the supervised agent
beeline update [--check|--status|--rollback|--force]
                                      Self-update the installed bundle

Runtime state lives in ${XDG_STATE_HOME:-~/.local/state}/beeline/agents/<agent-pubkey>/. The active bundle is ~/.local/lib/beeline.

Tool reference

Two MCP surfaces are mounted into every agent session.

beeline-readonly-mcp — reading, in a Room and in a corner:

Tool	What it does
list_files, read_file	Walk and read the checkout
search_text	Search the checkout
git_log, git_show, git_diff, git_status	Read repository history and state
read_agent_file	Read the agent's approved skills or Workspace memory
write_memory	Replace the agent's private Workspace MEMORY.md — the only memory write a Room allows

beeline-agent — acting, host-governed:

Tool	Where	What it does
open_corner	Top-level Rooms	Open one write-enabled corner with a ≤24-word objective
pr_checks_status	Corners	Read the server-posted checks verdict and human hold state
attach_file	Everywhere	Attach one file from the checkout or scratch dir to the reply
create_schedule, list_schedules, delete_schedule	Everywhere	Run a prompt again later — interval minutes or a 5-field cron
request_grant	Everywhere	Ask the owner for reach outside the sandbox
run_granted_command	Everywhere	Run a command an approved grant covers, outside the sandbox

The app

Beeline is on both stores:

• App Store
• Google Play

Sign in with GitHub, and the app hands you the pairing code that npx usebeeline connect asks for.

Beta

Beeline is 0.0.x and moves fast. Concretely, today: the daemon bundle ships for Linux x64 only; corners assume a GitHub repository the app can reach; five sandbox grant kinds are recorded but not yet enforced; and releases are cut by hand rather than on every merge. The pieces described above are the ones that work.

One README for GitHub and npm

packages/usebeeline/README.md is the canonical file. The repository's root README.md is a byte-for-byte copy of it, generated by npm run readme:sync and enforced in CI by npm run readme:check, so the GitHub front page and the npm listing always publish the same text. Edit the canonical file, then run the sync.

Because one file is rendered from two directories, every link in it is absolute.

Development

git clone https://github.com/Beeline-Work/beeline.git
cd beeline
npm install
npx turbo run build
npm run lint
npx turbo run test

The published CLI is a single bundled file built from apps/body:

npm run build -w @beeline/body
npm run build -w usebeeline     # esbuild apps/body/dist/cli.js -> packages/usebeeline/dist/usebeeline.mjs

Repository map:

beeline/
├── apps/
│   ├── auth/          GitHub identity and repository install ceremony
│   ├── body/          The daemon: harness sessions, Room turns, corners, self-update
│   ├── gate/          Relay, repository, and provisioning primitives
│   ├── mobile/        The phone app
│   ├── push-gateway/  Server-indexed Room surfaces and push delivery
│   └── server/        The monolith: Workspaces, Rooms, membership, grants
└── packages/
    ├── api-contract/  Shared vocabulary — faces, grants, system events
    ├── buzz-client/   Signed client for the indexed surfaces
    ├── nostr/         Schnorr-signed events and npub/nsec identity
    └── usebeeline/    This package

The product spec is spec.md, agent-facing conventions live in CLAUDE.md, and the UI contract lives in DESIGN.md.

License

usebeeline is published as UNLICENSED: free to install and run, not licensed for redistribution. A public source licence has not been chosen yet.