Skip to content

The .n45/ folder

When you run npx n45-ai init, N45 creates a .n45/ directory at the root of your project. Everything N45 needs to operate lives there.

Structure

.n45/
├── docs/           # foundational documents about your project
├── planning/       # active work — discoveries, specs, roadmaps, tasks
├── worktree/       # isolated agent workspaces (git worktrees) during execution
└── tmp/            # staging area for files being written

Where's the binary?

The N45 binary doesn't live in your project. It's downloaded to a shared cache in your home (~/.n45/bin/) and reused across projects. Slash commands invoke it under the hood — you don't need to call it directly.

What goes where

docs/

Foundational documents generated on first run and updated as your project evolves:

  • STACK.md — language, runtime, framework, build tooling
  • PATTERNS.md — architectural conventions found in your code
  • PROJECT.md — domain overview, modules, entry points
  • RUNBOOK.md — how to start, test, and deploy

See Project documents for full details.

planning/

Active and completed work artifacts. Every structured feat or fix creates files here:

  • Discoveries
  • Specs
  • Roadmaps
  • Task files (one per task)
  • Retrospectives (on roadmap close)

worktree/

Isolated workspaces where executor agents do their work during a flow. Each agent gets a dedicated git worktree at worktree/agent-<hash>/ — a copy of the active branch where it writes code without touching your working tree. When done, N45 merges it back and removes the worktree. Transient and N45-managed — don't edit or commit it.

tmp/

Where draft files are staged before being persisted. Not for manual edits — N45 writes here and reads back through its own commands.

What to commit

All of .n45/ is safe and recommended to commit:

  • docs/ and planning/ are your team's shared context

Add .n45/tmp/ and .n45/worktree/ to your .gitignore if N45 didn't add them for you. Everything else should be tracked.

What N45 won't touch

Anything outside .n45/ is owned by your project. N45 only writes outside .n45/ through dedicated executor agents during a flow — and those changes always pass through a branch and commit.