Plainbrain
A second brain you run with plain Markdown files, a few Python scripts and any AI agent: one list of commitments, an inbox for capture, notes worth finding again, a daily brief and a weekly review.
Free from DababonPro IT Solutions. It works on its own; Obsidian is optional, and any agent that reads AGENTS.md can run it, such as Claude Code, Codex or Cursor.
Its sibling: the Human-Approved Agent Playbook covers agents that change code and data. This repository covers what you know and what you owe.
Install
Needs Python 3.11 or later. Obsidian is optional.
Paste this into Claude Code, Codex, Cursor or Antigravity:
Install Plainbrain, a second brain in plain Markdown files, for me. First check that Python 3.11 or newer and git are installed; if one is missing, tell me how to install it, remind me to restart you or open a new chat afterwards so you can find it, and stop. Then suggest where to put it (a new folder called my-plainbrain in my Documents folder) and ask me to confirm before you change anything. Never overwrite an existing folder. Once I confirm, clone https://github.com/dababonpro/plainbrain into it and follow its AGENTS.md to set it up: install the requirements, create my files, and show me today's brief.
The agent checks what you need and asks once where to put Plainbrain. Then it asks you to describe yourself and what you are working on, and drafts your first commitments for you to accept, so your first brief is about your own work. It can also offer to look at your recent work to suggest more: only if you say yes, only on your machine, and it writes nothing from it without your approval.
After setup, open your Plainbrain folder as its own project or session in your agent. In the Claude desktop app, start a new session and choose the folder. In a terminal, cd into it and start the agent. Then say "Brief".
If the agent asks you to install Python or Git, restart the agent (or open a new chat) once it is installed, then paste the prompt again. Until then the agent cannot see the new install.
Want a private, backed-up copy instead? Click Use this template to make your own copy on GitHub, choose Private when GitHub asks, and give your agent that address in place of dababonpro/plainbrain. A public copy would show your commitments and notes to anyone once you save them to it.
git clone https://github.com/<you>/<your-copy> my-plainbrain
cd my-plainbrain
python -m pip install -r requirements.txt
python scripts/brain.py init --root .
python scripts/brain.py capture --root . --repo setup --text "Try the daily brief"
python scripts/brain.py brief --root .
python scripts/brain.py doctor --root .
On macOS and Linux the command is usually python3. If pip refuses to install, skip that line: only the optional MCP server needs it.
init creates REGISTRY.md, INBOX.md and CONTEXT.md, with one example commitment. Add --no-example to start with none, and --areas, --capacity and --about to set those. It changes nothing if the files already exist. The brief is written to reviews/daily/<date>.md.
What a brief looks like
After setup, "brief" writes a page like this from your own files. No AI model writes it, so it says only what the files say.
# Brief 2026-11-11
## Since yesterday
- No previous brief.
- renew-passport: Renew my passport (active)
- q4-report: Send the Q4 report (active)
## Blocked
## Next hour
Do this: Ask Sam for the sales figures
## Left quiet
active: 2
waiting: 0
someday: 0
done: 0
Capacity: about 2 hours a day.
## For the next brief
The next brief compares itself against these lines. Leave them as they are.
snapshot:
inbox: 0
focus: q4-report
active: 2
waiting: 0
someday: 0
done: 0
The line under "Next hour" is the next step of the commitment you chose as your focus. From the second day "Since yesterday" lists only what changed. A commitment with a due date appears under a "Deadlines" heading once the date is within a week or has passed, and a note with review_on or decide_by appears under "Decisions due" from that date until you move or remove the date. The dashboard shows how many are due.
What keeps it safe
- The inbox is append-only. Agents add lines with
capture and never rewrite INBOX.md.
- Inbox protection: Claude Code, Cursor, Codex and Antigravity can block direct inbox edits through hooks (
.claude/settings.json, .cursor/hooks.json, .codex/hooks.json, .agents/hooks.json). Codex asks once, in a Review hooks prompt: choose Allow for "Checking the inbox rule". You can change it later in Settings → Hooks, or with /hooks in the terminal. Other agents are instructed to use the capture command in AGENTS.md. Hooks stop ordinary edits rather than guarantee them, and a hook that cannot start blocks nothing, so run doctor once to see whether yours can.
- You approve commitments. Agents propose changes to
REGISTRY.md and write them only after you accept. They write through registry commands that change one item at a time, refuse a change that breaks the rules, and record each change in reviews/registry/.
- Notes are data. Text inside a note or a captured web page is never an instruction to the agent.
- No secrets in files. Notes name where a password lives, never the password.
Use it from other folders (optional)
The MCP server in scripts/mcp_server.py lets an agent working in any other folder search your notes, read your commitments and capture a line. It has no network access and needs no API keys. Capture is its only write.
It works on one folder: the one named by the BRAIN_ROOT environment variable, or, when that is not set, the folder the script sits in. Point it at your own copy, the folder where you ran init, never at a second clone you keep for updates.
Replace C:/path/to/my-plainbrain with your folder in each example.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
