Skip to main content

Getting Started

cognitiveOS is an AI-powered filesystem scaffold for developers with executive dysfunction. Your AI agent reads your project state automatically, so you open your laptop and know exactly what to do, instead of spending 30 minutes remembering where you were.

Free. Open source. MIT. No servers, no accounts, no database. Just markdown files on your machine.

Install

Run this inside any project:

cd your-project
npx cognitiveos init

Answer 3 questions. Done in under 60 seconds. Open your AI agent and start working. It already knows your context.

What it generates

your-project/
├── AGENTS.md        routing table, your agent reads this automatically
├── CLAUDE.md        same, for Claude Code
├── STATE.md         your current-state snapshot: focus, blockers, open loops
├── brain-dump/      capture everything, no filter
├── queue/           what's next, already sorted
├── focus/           the ONE thing right now (one task, enforced)
├── projects/        active work, max 3
├── ideas/           captured, not committed
├── someday/         not now, not never
└── sessions/        auto-logged history

Each zone folder also gets its own CONTEXT.md, and init writes a keeper subagent plus the deterministic session hooks for whichever AI agents you selected. Your agent reads STATE.md at session start and updates it at session end, via hooks, automatically. You never run a "save" command. You never maintain anything.

This is not a productivity system. It's a cognitive prosthetic. A productivity system asks you to maintain it. This maintains itself.

Your first session

  1. Run npx cognitiveos init in your project. First question is which AI agent(s) you use (multi-select, all ticked by default), then project type, then your project's name.
  2. Open your AI agent (Claude Code, Codex, Antigravity, Cursor). It reads CLAUDE.md / AGENTS.md and loads your context automatically. First time in, it offers a 60-second, 6-question setup so your project context isn't blank. See The Keeper.
  3. Run cognitiveos start any time to print Mission Control, exactly where you left off, in your terminal.
  4. Capture stray thoughts with cognitiveos dump "..." without breaking flow.
  5. Run cognitiveos check to confirm everything is wired correctly.

Next steps

  • Commands: full reference for init, start, dump, check, install-skill.
  • The Zones: what each folder means and when to use it.
  • Agent Setup: wire your specific AI agent.
  • The Keeper: the maintenance subagent and first-run interview.

The bet: structure beats willpower.

Edit this page on GitHub →