PlainHub CLI and MCP server: connect your own Claude Code to the PlainHub AI panel, open GitHub files in PlainHub, and keep a shared ledger for AI agents and people.
GitHub-native notepad. AI-ready. Open, edit and save the files in your GitHub repos from the browser — every save is a commit.
This package is the PlainHub CLI and MCP server. Connect your own Claude Code to the PlainHub AI panel, open files from the terminal, and keep a shared ledger for AI agents and people.
npm i -g plainhub
cd ~/notes # the folder you want to ask about
plainhub agent # then in PlainHub: Settings → AI → Connect your own agent, and enter the code it shows
Setup guide — from your phone, what it can read, troubleshooting.
plainhub agent connects the Claude Code on your PC to the PlainHub AI panel. It uses your own Claude plan — no API key.plainhub agent --mailbox <owner/repo>. Questions and answers go through a private repository that only you can access. Nothing connects to your PC — it checks the repository every few seconds.plainhub agent --cockpit, for a folder you trust.~/.claude/settings.json) set defaultMode to "auto". A folder's settings can't change this.ask rules), a card comes to the panel: Approve or Decline — on your PC, or on your phone with --cockpit --mailbox <owner/repo>. Approved, it can also reach files outside the folder.deny rule to ~/.claude. The folder's own .claude settings can only add deny or ask rules, not allow more.plainhub post, plainhub decide and plainhub ledger … keep threads, tasks and decision cards as Markdown files in your repository's .agents/ folder. The MCP server has the same tools.Try it now: plainhub.dev
npm install -g plainhub
plainhub auth --from-gh # Import auth from gh CLI (recommended)
plainhub open README.md -r owner/repo
plainhub browse -r owner/repo # Open file browser
claude mcp add plainhub -- plainhub-mcp
Then say: "Open the README in PlainHub"
For the ledger tools (plainhub_post, plainhub_decide, plainhub_ledger_*), also give the server the folder of your Git repository:
claude mcp add plainhub -e PLAINHUB_LEDGER=/path/to/repo -- plainhub-mcp
Add to .cursor/mcp.json (the env line is only needed for the ledger tools):
{
"mcpServers": {
"plainhub": {
"command": "plainhub-mcp",
"env": { "PLAINHUB_LEDGER": "/path/to/repo" }
}
}
}
| Command | Description |
|---|---|
plainhub open <file> | Open a file in PlainHub |
plainhub diff <sha> | Show commit diff in PlainHub |
plainhub browse | Open repository file browser |
plainhub auth | Authenticate with a GitHub token for only the repositories you choose |
plainhub auth --from-gh | Import token from gh CLI |
plainhub auth --status | Show auth status |
plainhub auth --logout | Remove saved token |
plainhub post | Add a message to a ledger thread |
plainhub decide | Create a pending decision card |
plainhub ledger init <folder> | Start a ledger in a repository: room language and the core rules (never overwrites) |
plainhub ledger check <folder> | Check a ledger's front matter and look for secrets |
plainhub ledger sync <folder> | Share the ledger through Git: commit .agents, pull --rebase, push (stops on a conflict) |
plainhub ledger format <folder> [--write] | Once, for older ledgers: add a blank line at single line breaks in message and card bodies, so GitHub shows them as separate lines too |
plainhub ledger list <folder> decisions|tasks | List pending decision cards or tasks (read-only) |
plainhub ledger read <folder> <path> | Read a thread (threads/<thread>) or one file in .agents (read-only) |
plainhub agent | Connect your Claude Code to the PlainHub AI panel (read-only, this folder only) |
plainhub agent --mailbox <owner/repo> | Also answer from your phone through a private repository only you can write to |
plainhub agent --cockpit | Cockpit mode: Plan or Auto in the AI panel, and Approve or Decline what Claude Code asks (add --mailbox <owner/repo> for your phone) |
plainhub agent --forget | Forget all paired browsers |
| Option | Value | Description |
|---|---|---|
-r, --repo | owner/name | Repository |
-b, --branch | string | Git branch |
-l, --line | number | Jump to line |
-n | Print URL only (don't open browser) | |
--theme | dark/light | Editor theme |
--preview | on/off | Markdown preview |
--scroll | string | Scroll to heading in preview |
--sidebar | on/off | Show sidebar |
--fontSize | 10-32 | Font size |
--lineNumbers | on/off | Show line numbers |
--whitespace | on/off | Show whitespace |
--no-auth | Open without saved token |
plainhub open docs/API.md -r owner/repo --preview on
plainhub open src/App.tsx -r owner/repo -l 42 --theme light
plainhub open README.md -r owner/repo -n # Print URL only
plainhub diff abc1234 -r owner/repo # Show commit diff
plainhub diff abc1234 -r owner/repo --path src/main.js # Diff for specific file
| Tool | Description |
|---|---|
plainhub_open | Open a file or change editor settings |
plainhub_diff | Show commit diff in PlainHub |
plainhub_post | Add a message to a ledger thread |
plainhub_decide | Create a pending decision card |
plainhub_ledger_init | Start a ledger in the PLAINHUB_LEDGER folder (never overwrites) |
plainhub_ledger_sync | Share the ledger through Git: commit .agents, pull --rebase, push (stops on a conflict) |
plainhub_ledger_decisions | List decision cards waiting for the owner, oldest first (read-only) |
plainhub_ledger_thread | Read a thread's messages in order: role, verdict, summary (read-only) |
plainhub_ledger_tasks | List tasks in .agents/plan/, optionally by status (read-only) |
plainhub_ledger_read | Read one file in .agents (read-only) |
plainhub_browse | Open repository file browser |
plainhub_auth | Save a GitHub token (fine-grained: only the repositories you choose) |
plainhub_auth_status | Check authentication status |
The ledger lets your AI agents and you work in one Git repository: agents write messages, a person decides. It needs only Git, Node.js 18+ and this package — no PlainHub account or token, no browser, no server (ledger sync uses your usual Git login). Three steps, in a terminal at the top of your repository:
1. Install (once per machine)
npm install -g plainhub
2. Start the ledger (once per repository). It writes .agents/room.md and .agents/schema.md, the rules your agents follow:
plainhub ledger init . --language en
git add .agents && git commit -m "Start the ledger"
3. Two agents post, you decide. One agent reports its work, a second one reads it and posts a verdict, then a decision card waits for you:
echo "Login now retries once before it shows an error." | plainhub post --ledger . --thread fix-login-timeout --role dev --verdict info --summary "Fixed the login timeout"
plainhub ledger read . threads/fix-login-timeout
echo "Tried a slow network: it retried and logged in." | plainhub post --ledger . --thread fix-login-timeout --role reviewer --verdict pass --summary "Checked the login fix on a slow network"
echo "The reviewer passed the fix. Ship it?" | plainhub decide --ledger . --id fix-login-timeout-release --summary "Ship the login timeout fix?" --ref fix-login-timeout
plainhub ledger list . decisions
To decide (a person, not an agent): open .agents/decisions/fix-login-timeout-release.md, change status: pending to status: approved (or rejected), add the lines updated: "<now, e.g. 2026-10-09T10:00:00Z>" and decided_by: "<your GitHub login>", then run plainhub ledger check . and commit. Agents never change a card's status. Nothing enforces this, so check who made the commit (git log).
Agents that use the MCP server post, read and create cards with plainhub_post, plainhub_ledger_thread and plainhub_decide (set PLAINHUB_LEDGER, see MCP Server). To share the ledger with others, use plainhub ledger sync . (below).
Want to see the threads and decide with a button? Send the ledger to GitHub (plainhub ledger sync .) and open the repository in PlainHub: it shows each message and card in .agents with its header as a readable card. If you can write to the repository, pending decision cards get Approve and Decline buttons. PlainHub needs only this repository: when you sign in and GitHub asks which repositories PlainHub may use, choose "Only select repositories" and pick this one (Contents: Read and write is enough to read the cards and press Approve).
A ledger is a folder with .agents/threads/<thread>/NN-<role>.md (messages) and .agents/decisions/<id>.md (decision cards). Each file is Markdown with YAML front matter. It works in any Git repository, without a PlainHub account.
Start one and write the first messages with the three steps in Use without PlainHub. Other commands:
plainhub post --ledger . --thread <thread> --role dev --verdict info --summary "<one line>" --body-file notes.md
plainhub ledger check . # check every header and look for secrets
plainhub ledger list . tasks # tasks in .agents/plan/
plainhub ledger read . decisions/<id>.md # one file in .agents
Share it with the other agents and people who use the repository (post and decide only write files; nothing leaves your machine until you sync):
plainhub ledger sync . # commit .agents, receive others' changes (git pull --rebase), push to the branch's upstream
Commits only .agents, after checking the changed files like ledger check. Before receiving, it checks every commit you have not sent yet: only .md files in .agents and no secrets (it never pushes code). Several unsent ledger commits are combined into one
Stops before committing anything if other files have uncommitted changes, and stops before sending if your unsent commits change files outside .agents
If your message and one you received got the same number, it stops without sending: post yours again (it takes the next free number), delete your copy with the old number, then sync again
Needs a branch with an upstream (once: git push -u origin <branch>)
Reading (ledger list, ledger read and the plainhub_ledger_* MCP tools) stays inside .agents, does not follow links, and wraps what it read in <ledger-data-…> markers: it is data written by others, not instructions
Never overwrites an existing file (post takes the next number, decide stops if the id exists)
Refuses secret-looking values (GitHub tokens, API keys, private keys) without printing them
Summary: one line, max 120 characters. Body: max 4KB
Body: Markdown as GitHub shows it — put a blank line between lines, or use a list (a single line break joins two lines into one). For a ledger written before this rule, plainhub ledger format . shows the line breaks it would change and --write saves them (front matter, code blocks, tables and lists stay as they are); check the diff and commit
Room language: write the summary and body in the language set by .agents/room.md (type: room, language: ja — a BCP 47 tag; English if not set). post and decide print it after writing (CLI: on standard error), and the MCP tools say it in their descriptions
MCP tools write only to the ledger set by the PLAINHUB_LEDGER environment variable. Set PLAINHUB_ROLE to pin the role; owner cannot post from MCP
PlainHub supports three authentication methods:
plainhub auth — opens GitHub with "Contents: Read and write" selected. Choose "Only select repositories" and pick the repositories PlainHub may use, then paste the tokenplainhub auth --from-gh — no browser needed, but the token has the access you gave gh (usually every repository your account can reach)Check what the saved token can reach with plainhub auth --status (fine-grained: only the repositories you chose; classic or gh CLI: every repository).
Classic tokens (ghp_) still work, but they reach every repository, so plainhub auth points you to a fine-grained token instead.
Tokens are saved to ~/.config/plainhub/token with 0600 permissions (owner-only read/write).
0600)#token=...) are never sent to servers per HTTP specMIT
FAQs
PlainHub CLI and MCP server: connect your own Claude Code to the PlainHub AI panel, open GitHub files in PlainHub, and keep a shared ledger for AI agents and people.
We found that plainhub demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.