NightLoop CLI

Spec-first project OS for agentic development.

NightLoop scaffolds a structured workspace — tasks, specs, context packages, work sessions, operational insights, git discipline, and a synthwave TUI — as plain files agents and humans can share.

v0.2.0 introduces ProjectStore, unified work sessions, and deterministic operational insights. See CHANGELOG.md. Earlier 0.1.x security notes remain in SECURITY.md.

Install

npm install -g nightloop-cli

Requires Node.js ≥ 18.

Quickstart

cd my-project
nightloop init
nightloop spec create "Initial feature"
nightloop task create "Build initial feature"
nightloop work start task_001 --no-git    # optional: omit --no-git when using git
nightloop doctor
nightloop insight summary
nightloop tui          # operational dashboard (optional)

Reference (concepts first)

Shipped under docs/reference/ on init / adopt — product surface, not informal notes.

| Start here | Path | |------------|------| | Index | docs/reference/README.md | | Concepts (read before commands) | docs/reference/concepts/ | | Workflows | docs/reference/workflows/ | | Troubleshooting | docs/reference/troubleshooting/ |

Methodology kernel: docs/vision/METHODOLOGY_KERNEL.md. Categorized nightloop help and nightloop reference are Phase 11b.

Command reference (high level)

| Area | Commands | |------|----------| | Bootstrap | init, doctor, skills init | | Artifacts | spec create, task create, report create | | Work loop | work start\|status\|continue\|complete\|review\|doctor\|list | | Context | context build\|show\|list\|clean | | Git | git status\|start\|finish\|branches | | Review | agent review, agent pipeline list\|create | | Insights | insight summary\|risks\|reviews\|workflow\|metrics (+ legacy overview, workflow-docs, export) | | Board | board view\|export | | TUI | tui — Dashboard, Board, Work, Git, Context, Agents, … | | Other | metrics, release, run, provider, pack, security, gh, adopt, recovery, docs, architecture |

Run nightloop --help and nightloop <command> --help for the full tree.

Work sessions (v0.2)

nightloop work start task_001
nightloop work continue <session-id> --force   # refresh context
nightloop work review <session-id>
nightloop work doctor <session-id>
nightloop work complete <session-id>

Sessions persist under .nightloop/sessions/ with a human briefing .md per session.

Operational insights (v0.2)

Deterministic JSON derived from filesystem artifacts (no LLM):

nightloop insight summary
nightloop insight workflow          # health findings
nightloop insight risks             # weighted risk profile
nightloop insight metrics --json

Snapshot: .nightloop/store/insights.json (rebuildable).

Legacy portfolio/maturity markdown: nightloop insight overview, nightloop insight workflow-docs, nightloop insight export.

Security & safety notes

• nightloop security runs local regex/heuristic scans. It is not a substitute for professional security review or OWASP certification.
• .nightloop/safety.json lists paths agents should treat as protected. NightLoop does not enforce those rules in code today — they are guidance for humans and agents unless you add your own CI gates.
• nightloop run sends prompt file contents to your configured provider URL. Keep API keys in environment variables (providers.json stores env var names, not keys).
• nightloop init merges recommended .gitignore entries for .nightloop/runs/, .nightloop/providers.json, and .env*.

See SECURITY.md for reporting vulnerabilities and known limitations.

Methodology skills

nightloop init and nightloop skills init generate operational skills under docs/skills/ (plus SKILL_TEMPLATE.md), derived from docs/vision/.

nightloop context build <task-id> auto-selects skills from task metadata. You can also list skills in the task file:

**NightLoop Skills:** context-discipline, safe-local-data-handling

See docs/vision/METHODOLOGY_KERNEL.md and src/lib/skills.ts (SKILL_REGISTRY).

How it works

.nightloop/
  config.json        — project identity, workflow mode
  safety.json        — protected path guidance for agents
  store/             — ProjectStore + insights snapshots (derived, rebuildable)
  sessions/          — work session state (v0.2)
  context/           — generated agent context packages
  runs/              — provider run artifacts (gitignore recommended)

docs/
  specs/             — feature specs (Markdown)
  tasks/             — task files (Markdown)
  reports/           — implementation reports

Philosophy

1. Spec first. Define scope before implementation.
2. Tasks drive work. One task → one branch → one report (when strict mode enabled).
3. Sessions track continuity. Resume operational state without re-scanning the tree ad hoc.
4. Agents are participants. NightLoop tracks artifacts; you stay in control.
5. Files over databases. Markdown + JSON — no vendor lock-in.

License

MIT — NaguiPinetta/nightloop-cli