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 published package name is second-brain-os. The unscoped name second-brain on npm refers to a different project; this repo publishes as second-brain-os.

After publishing (or once a release exists on npm), 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 installing:

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).

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 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 once published.

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). 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.