second-brain-os

Second Brain OS

Second Brain OS is a local-first command-line tool for running a personal knowledge system (“second brain” / PKM) entirely on your machine:

• Markdown files are the source of truth: inbox, areas, goals, projects, tasks, resources, notes, reviews, and archives live as normal .md files you can open in any editor or sync with Git.
• SQLite stores an index of metadata so listing, search, dashboards, and health checks stay fast and consistent with what is on disk.
• The second-brain-os CLI (short alias second-brain) provides capture, organize, list, show, search, today, dashboard, weekly review, archive / restore, doctor (validation + repair), and config—with human-friendly output and a stable --format json mode for scripts and AI agents.

There is no required cloud service. Optional OpenAI can be enabled later for richer flows; without it, the CLI uses deterministic behavior and heuristics.

On disk, each vault still uses a .second-brain/ folder for config and the local database path (that directory name is unchanged).

What this project is for

Goal	How Second Brain OS helps
Capture quickly	Raw inbox capture or typed entities (capture) with optional areas/projects.
Organize	Heuristic inbox analysis, promote to typed entities, link, rename, reclassify (organize).
See your day	today and dashboard show aggregate tasks and context from local state.
Find things	list, show, search over indexed metadata and content.
Stay healthy	doctor reports drift; doctor --repair re-syncs index with disk when needed.
Agents & automation	JSON envelope (ok, errors, warnings, next_actions, data) on every command.

Workspace model: Each “vault” is a folder containing .second-brain/config.yml and your Markdown tree. The CLI discovers it by walking up from the current directory, or via --workspace / SECOND_BRAIN_WORKSPACE.

Install (from npm)

The package is published as second-brain-os on the npm registry. The unrelated package second-brain is a different project—install second-brain-os for this CLI.

Install globally:

npm install -g second-brain-os
second-brain-os --help
# optional short alias (also installed):
second-brain --help

Or run a one-off without a global install:

npx second-brain-os doctor --format json --workspace ~/SecondBrain

Requirements: Node.js 20+. The dependency better-sqlite3 includes native code; on some systems you need a build toolchain for npm install to compile (common on Windows without Visual Studio Build Tools).

Documentation: This file is the project overview. For a full user and integration guide (architecture, JSON envelope, commands, Cursor skill, troubleshooting), see docs/USER_GUIDE.md (also included in the published npm package under docs/). For contributors—setup, scripts, testing, database workflow, and releases—see docs/DEV_GUIDE.md.

Quick start

second-brain-os init
cd ~/SecondBrain
second-brain-os capture "remember to book dentist"
second-brain-os doctor --format json

Non-interactive init (CI / scripts):

second-brain-os init --non-interactive --workspace ./my-vault

Point commands at a vault that is not your current directory:

second-brain-os doctor --format json --workspace D:\second-brain
second-brain-os capture --workspace D:\second-brain "quick note"

Or set for the session:

# PowerShell
$env:SECOND_BRAIN_WORKSPACE = "D:\second-brain"
second-brain-os doctor --format json

Install from source (development)

git clone https://github.com/NourEldinShobier/second-brain-os.git
cd second-brain-os
npm install
npm run build
npx second-brain-os --help

Note: npx second-brain-os from a clone resolves this package on disk. If you cd into a vault folder that is not an npm package, npx may fail with could not determine executable to run. Use npx from the cloned repo, pass --workspace to your vault, use npm link after npm run build, or install second-brain-os from npm and use the global second-brain-os / second-brain commands.

Global CLI flags

Flag	Purpose
--format pretty|markdown|json	Output style (--json = JSON).
-n, --non-interactive	No prompts.
-q, --quiet	Minimal output.
--dry-run	Preview where supported.
--workspace <path>	Vault root.

Commands (overview)

Area	Commands
Setup	init, config show, config set
Capture	capture (inbox or --type area | goal | project | task | resource | note)
Organize	organize analyze, promote, link, rename, reclassify
Surfaces	today, dashboard show
Query	list, show, search
Maintenance	review weekly, archive, doctor

Full detail: docs/USER_GUIDE.md (architecture, JSON envelope, examples, troubleshooting).

JSON output (for scripts & agents)

With --format json or --json, success and failure responses share a stable shape: ok, schema_version, data, warnings, errors, next_actions. Parse ok and errors before treating a run as successful.

Cursor skill (optional)

This repository includes a Cursor Agent Skill under .cursor/skills/second-brain-os/ so assistants prefer real CLI invocations and JSON output instead of hand-editing the database. See docs/USER_GUIDE.md §11.

Repository layout (high level)

Path	Role
src/cli/	Commander program, commands
src/application/	Use cases (capture, doctor, etc.)
src/infrastructure/	Markdown repo, SQLite/Drizzle, config
src/domain/	Types, validation
drizzle/	SQL migrations shipped with the CLI
dist/	Compiled output (produced by npm run build)

Scripts (development)

Script	Purpose
npm run build	Compile TypeScript to dist/
npm test	Run Vitest
npm run typecheck	Typecheck
npm run lint	ESLint

Publishing to npm (for maintainers)

• Account: Create an account on npmjs.com and sign in locally: npm login.
• Name: This repo publishes as second-brain-os. The global second-brain name on npm is a different package—do not overwrite it. The bin field installs both second-brain-os and second-brain entry points for this project. To use a scoped name instead (e.g. @your-org/second-brain-os), change "name" in package.json and set "publishConfig": { "access": "public" } for a public scoped package.
• Version: Bump with npm version patch (or minor / major) so package.json and git tag stay aligned.
• Build: prepublishOnly runs npm run build; the tarball includes only files listed in package.json (dist/, drizzle/, README.md, LICENSE, docs/).
• Dry run: npm pack and inspect the .tgz, or npm publish --dry-run.
• Publish: npm publish (use --access public for scoped public packages). npm may require two-factor authentication for publishing: use npm publish --otp=<code> from your authenticator, or a granular access token with publish permissions. package.json repository / bugs / homepage should match this GitHub repo.

Native module: better-sqlite3 compiles on install for the user’s platform; no separate publish step for binaries unless you add prebuild automation later.

License

MIT — see LICENSE.