Second Brain

A personal knowledge base that lives in this folder. Drop content in, have it organized automatically, ask questions, and get sourced answers — through Claude Code, OpenAI Codex, or OpenCode skills, or a local web dashboard (available as a downloadable macOS app).

---

START HERE — first run

Just cloned this? Do these steps in order. It’s the same in Claude Code, Codex, or OpenCode.

1. Clone the repo (your agent may have already done this).
2. Restart your agent so it’s running inside the SecondBrain folder. Agents load their skills and read config at startup, based on the folder they open in. If you cloned from your home directory, the /second-brain-* skills don’t exist in that session yet — quit and reopen the agent here. (Skipping this is the #1 reason “the commands don’t work.”)
3. Run setup: /second-brain-setup (Claude Code) or $second-brain-setup (Codex). It asks for your interests and engine, then writes your config.
4. Restart your agent once more. This loads the config setup just wrote. Now everything works.
5. Start using it — pick a path below.

No CLAUDE.md / AGENTS.md in the folder? That’s expected. They’re generated by /second-brain-setup and are intentionally absent from a fresh clone. The CLAUDE.md.example / AGENTS.md.example files show what setup will create — you don’t need to touch them by hand.

Easiest (no terminal) — the app. After setup, download SecondBrain.app, launch it, and point it at this folder. The dashboard re-reads your config every time it starts, so there’s no restart juggling. Best path for non-technical users.

In your agent (CLI). After the step-4 restart, try: /second-brain-import-md → /second-brain-ingest → /second-brain-query "…" (Codex: swap the leading / for $). Full command list is under Usage below.

Extra Credit Install the bundled Chrome extension for easy web-page import.

---

What it does

The system has three tiers:

Content flows in one direction: raw/ → ingest → wiki/ → query → outputs/.

---

Prerequisites

• An agent CLI on your PATH — any one:

  • Claude Code (claude) — install from claude.ai/code, then sign in. (default)
  • OpenAI Codex (codex) — install per OpenAI’s Codex CLI docs, then codex login (or set CODEX_API_KEY).
  • OpenCode (opencode) — install per OpenCode’s docs, then opencode auth login to configure a model provider (any provider on Models.dev, including the free OpenCode Zen models).

  All three run the same Second Brain skills; pick one at setup. Switch any time by changing AGENT_ENGINE in .env.

• Python 3 (macOS system Python is fine — no pip install needed).

• (optional) The Craft MCP integration — configured in Claude Code’s MCP settings, in ~/.codex/config.toml for Codex, or in OpenCode’s config for OpenCode — if you want Craft import.

---

First-time setup

/second-brain-setup     # Claude Code
$second-brain-setup     # Codex

This asks which agent engine you use, records it in .env, declares your interests, and writes the configuration file — CLAUDE.md and AGENTS.md both, so you can switch engines later. (CLAUDE.md is read by Claude Code; AGENTS.md by Codex and OpenCode.) Run it once, or again any time you want to update your interests.

Restart after setup. Skills and config load at agent startup, so quit and reopen your agent inside this folder once setup finishes — see START HERE for the full first-run sequence.

---

Agent engine — Claude Code, Codex, or OpenCode

Every Second Brain operation is an agent skill — a SKILL.md of plain instructions. Claude Code, OpenAI Codex, and OpenCode run the same skills, so you can use whichever you prefer. The choice lives in one place: AGENT_ENGINE in .env.

/second-brain-setup writes both CLAUDE.md and AGENTS.md (identical content), and the canonical .claude/skills/ tree is exposed to Codex and OpenCode through a .agents/skills link the dashboard creates automatically — so nothing else needs changing when you switch.

Switching engines

1. Set AGENT_ENGINE=opencode (or claude / codex) in .env at the vault root.
2. Restart the dashboard with ./run.sh — the value is read at startup.

That’s the whole switch. The dashboard’s top status bar shows the active engine (the “… agent” tile), and the rest of the vault — interests, raw content, wiki — is untouched by the choice. Custom binaries stay independent: CLAUDE_BIN is used only under claude, CODEX_BIN only under codex, and OPENCODE_BIN only under opencode, so flipping between them always relaunches the right one. With OpenCode you can also pick a model tier from the dashboard’s engine menu — including the free OpenCode Zen models (Hy3, DeepSeek Flash, Nemotron Ultra).

Security note: the engines enforce the sandbox differently. Claude Code denies Bash/network and path-scopes writes to the vault. Codex and OpenCode are trust-based: Codex confines writes via --sandbox workspace-write and OpenCode runs with --auto (auto-approves anything not explicitly denied) scoped to the vault directory, but both can still run shell commands inside the vault — neither has a per-tool “deny Bash”. Read dashboard/README.md before choosing for an untrusted-content workflow.

---

Usage — Claude Code / OpenCode (/) or Codex ($) skills

All knowledge-base operations are agent skills. Run them by typing the skill name in a session open to this folder — prefixed with / under Claude Code or OpenCode, or $ under Codex (e.g. /second-brain-query "…" or $second-brain-query "…"). The commands below show the / form; swap the leading / for $ on Codex.

Capture

You can also drop files directly into raw/ — a .md note, a PDF, even an image — and they will be picked up on the next /second-brain-ingest. The skills below are convenience wrappers that handle conversion (e.g. PDF text extraction) and Craft/web fetching before writing to raw/.

Organise

Retrieve

Notes

• Ingest is explicit — new content in raw/ does not appear in the wiki until you run /second-brain-ingest.
• Ingest fingerprints source bytes with SHA-256. A changed filesystem timestamp triggers a hash comparison, so genuine in-place edits are re-ingested while a branch checkout or touch does not cause a full-vault rebuild. Existing manifested files are silently fingerprinted when upgrading; unmanifested files remain ready to ingest.
• The wiki is AI-managed — never edit files in wiki/ directly.
• raw/ is the source of truth — ingest never edits it. Users and importers may update an existing source in place; its changed bytes will be detected on the next ingest.

---

Usage — Interactive dashboard

The dashboard is a local web UI that surfaces the same six operations without opening a terminal.

macOS app (easiest on Mac)

Prefer a real app to running a script? Download SecondBrain.app — a signed, notarized macOS app that runs the dashboard for you: it starts the bridge, shows the dashboard in its own window, lives in the Dock while running, lets you switch engine (Claude / Codex / OpenCode) and model tier from a menu, and shuts the bridge down when you quit.

⬇ Download SecondBrain.app — notarized, so it opens with a normal double-click (no right-click, no Gatekeeper prompt).

It’s a companion to this repo, not a standalone download: clone the repo and have an agent CLI (claude, codex, or opencode) on your PATH, then point the app at your vault folder on first launch. Build it yourself or read more in macos-app/README.md.

Start from the terminal

./run.sh

The bridge prints http://127.0.0.1:4173/ and opens it in your browser. Stop with Ctrl-C.

run.sh is idempotent — if the port is already occupied by a previous bridge it kills it before starting a fresh one.

Custom port

PORT=4180 ./run.sh
# or directly:
python3 dashboard/bridge.py --port 4180 --no-open

What the dashboard provides

• Hero query box — ask a question and read the rendered answer directly in the page.
• Navigation bar — browse past answers and wiki articles.
• Import controls — paste Markdown, drop/select any file (PDF, PowerPoint, Word, Excel, CSV, image, plain text), import from a URL, or specify a Craft folder and document name. PowerPoint decks (.pptx), Word documents (.docx), Excel workbooks (.xlsx/.xlsm), and CSVs are converted to Markdown instantly, in-process — no model call — landing in raw/pptx/, raw/docx/, raw/xlsx/, and raw/csv/.
• Pending row — when raw files are waiting, a row appears under the status strip saying how many aren’t searchable yet, with an Update wiki button. It disappears once everything is folded in.
• Wiki maintenance — Update wiki and Run lint sit pinned at the bottom of the sidebar under the Wiki tab. Both write a dated report into outputs/ and open it, so past runs stay browsable in the Home list alongside your answers.
• Wiki edit boxes — while viewing a lint report or any wiki article, a suggestion box lets you describe an edit in plain English and apply it directly without touching files manually.
• Status strip — wiki article count, genuinely new or content-changed raw items, and last ingest time, derived from the filesystem with no model call.

How it works

The dashboard is a static HTML page. Every long operation fires a POST /run request to a tiny Python bridge (dashboard/bridge.py) which execs the configured agent — claude -p "/second-brain-..." --output-format json, codex exec "$second-brain-..." --sandbox workspace-write when AGENT_ENGINE=codex, or opencode run "/second-brain-..." --format json --auto --dir when AGENT_ENGINE=opencode — and streams the result back. Knowledge synthesis remains in the skills; deterministic ingestion state is shared by the bridge and direct CLI through dashboard/ingest_state.py.

Chrome extension

A companion browser extension lets you import any page directly from Chrome without opening the dashboard first. It connects to the same local bridge, so the bridge must be running.

Install (one-time):

1. Open Chrome and navigate to chrome://extensions.
2. Enable Developer mode (toggle in the top-right corner).
3. Click Load unpacked.
4. Select the chrome-extension/ folder at the root of this repo.

The “Second Brain Importer” extension will appear in your toolbar (pin it for easy access).

On the Mac app, you can also use App → Install Browser Extension…, which reveals the chrome-extension/ folder in Finder and opens chrome://extensions for you — then just do steps 2–4 above.

Usage:

1. Start the bridge with ./run.sh (or keep it running in the background).
2. Browse to any page you want to capture.
3. Click the Second Brain icon in your toolbar and press Import this page.

The extension extracts the page’s main content, converts it to Markdown, and saves it to raw/web/ — identical to /second-brain-web-import but triggered from the browser. For paywalled pages where the extension can’t extract content, use /second-brain-web-import with paste mode instead.

Local settings (.env)

Create a .env file at the vault root to override defaults without editing any code:

# Which agent CLI backs the skills: claude (default), codex, or opencode.
AGENT_ENGINE=claude

# Use a different claude binary (e.g. a Max subscription account):
CLAUDE_BIN=claude-personal

# Use a different codex binary (used when AGENT_ENGINE=codex):
CODEX_BIN=codex

# Use a different opencode binary (used when AGENT_ENGINE=opencode):
OPENCODE_BIN=opencode

# Show the Craft import card in the dashboard (Craft MCP must be configured for your engine):
CRAFT_ENABLED=1

The .env file is gitignored — it never leaves your machine.

Permissions

The dashboard runs each skill without bypassPermissions. The bridge grants only the tools a skill needs, denies Bash/network/subagent tools outright, and confines Write/Edit to this folder — so a prompt-injection in imported content can’t run commands or write outside the vault. It also gates every request with a per-session token and an Origin check so other web pages can’t drive it. See dashboard/README.md for the full model.

Avoid “fixing” a permission denial by adding bare Write, Edit, or Bash to permissions.allow in .claude/settings.local.json — that re-opens the vault-escape hole. Add the narrowest (path- or command-scoped) rule instead.

Troubleshooting

---

Project layout

SecondBrain/
├── raw/                        Source content (ingest-read-only; importers may update)
│   ├── craft/                  Notes imported from Craft
│   ├── pdf/                    Text extracted from PDFs
│   ├── pptx/                   Markdown extracted from PowerPoint decks
│   ├── docx/                   Markdown extracted from Word documents
│   ├── xlsx/                   Markdown tables extracted from Excel workbooks
│   ├── csv/                    Markdown tables extracted from CSV files
│   ├── images/                 Visual descriptions of imported images
│   ├── web/                    Pages fetched by web-import
│   └── .ingest-manifest.json   Machine-managed ingestion state
├── wiki/                       AI-organised topic articles
│   └── INDEX.md                Master topic index (rebuilt on every ingest)
├── outputs/                    Query answers, lint reports, ingest reports
├── .claude/skills/             Agent skills — the engine behind every command (Codex and OpenCode read them via the .agents/skills link)
│   ├── second-brain-query/        ask the knowledge base
│   ├── second-brain-ingest/       fold raw/ into wiki/
│   ├── second-brain-lint/         scan the wiki for issues
│   ├── second-brain-edit-wiki/    apply natural-language edits to articles
│   ├── second-brain-import-{md,web,pdf,file,craft}/   capture content
│   └── second-brain-setup/        first-time configuration
├── dashboard/                  Local web UI
│   ├── bridge.py               Python stdlib HTTP server + claude/codex/opencode proxy
│   ├── index.html              Single-page dashboard
│   ├── styles.css              Visual design
│   ├── app.js                  Front-end controller
│   ├── fonts/                  Self-hosted Newsreader + Figtree webfonts (OFL)
│   ├── lib/marked.min.js       Vendored Markdown renderer
│   └── lib/purify.min.js       Vendored DOMPurify (HTML sanitiser)
├── chrome-extension/           Browser extension (load unpacked in Chrome)
├── macos-app/                  Native macOS app that runs the dashboard (Swift source + build/release scripts)
├── run.sh                      Start the dashboard (idempotent port cleanup)
├── CLAUDE.md                   Vault schema + your declared interests (gitignored — personal)
├── CLAUDE.md.example           Template to copy when setting up a new vault
├── .env                        Local overrides: CLAUDE_BIN, CRAFT_ENABLED (gitignored)
└── specs/                      Feature specs and implementation plans

---

Further reading

• CLAUDE.md — vault schema, folder rules, and your declared interests.
• specs/001-personal-knowledge-base/spec.md — PKB feature specification.
• specs/002-interactive-dashboard/spec.md — Dashboard feature specification.
• specs/002-interactive-dashboard/plan.md — Implementation plan and architecture.
• specs/002-interactive-dashboard/contracts/bridge-http.md — Bridge HTTP API.