Project layout

The kit doesn't impose a layout, but everything it does is relative to a few folders you choose. This is the layout the kit's own example and its real consumers use.

The agent's repository

my-agent/
├── package.json          "type": "module", depends on @falkenslab/agent-kit
├── tsconfig.json
├── .env                  CLAUDE_CODE_OAUTH_TOKEN=… (git-ignored)
├── .gitignore            .env, .run/, node_modules/
├── agent.ts              the entry point: spec, config, chat
├── prompts/              system prompt templates (createPromptLoader)
│   └── system.md
├── plugin/               the agent's own skills and slash commands
│   ├── .claude-plugin/
│   │   └── plugin.json   { "name": "my-agent" }
│   ├── skills/
│   │   └── some-skill/SKILL.md
│   └── commands/
│       └── some-command.md
└── .run/                 one folder per run (git-ignored)
    ├── history.jsonl     the ↑/↓ history, shared by every run
    └── 2026-09-29T10-15-00-000Z/
        ├── session.log         what the terminal showed, as plain text
        ├── transcript.jsonl    every tool call and result, secrets redacted
        ├── conversation.jsonl  the SDK's transcript of the conversation
        ├── subagents/          each subagent's transcript
        └── session.json        the SDK session's id, to resume it

The workspace the agent works in

projectDir is the session's working directory. When the agent has notes or sources, they usually live inside it:

workspace/                projectDir: the session's cwd
├── .claude/              the project's own skills, commands and settings (loaded by default)
│   ├── skills/
│   └── commands/
├── CLAUDE.md             project instructions (loaded by default)
├── .mcp.json             extra MCP servers for this workspace (optional)
├── knowledge/            knowledgeDir: the agent's notes (read/write)
│   ├── index.md
│   ├── log.md
│   └── …
└── sources/              sourcesDir: originals (read-only for the agent)

For a single-purpose agent the workspace can be the agent's own repository (projectDir: __dirname, as in Captain Whiskers). An agent that serves many workspaces (one per course, per customer…) takes the workspace from its configuration and keeps its own code elsewhere.

Where each piece is configured

Folder	Set by	Page
projectDir	BaseSessionConfig.projectDir	Session config
knowledgeDir, sourcesDir	BaseSessionConfig	Knowledge base
Plugin folders	AgentSpec.pluginRoots()	Skills and plugins
The runs folder	runsDir option of the chat	Runs and resuming
The run folder	passed to your session opener (run.dir)	Session options
The history file	historyPath option of the chat	Ink chat

Resolve folders to absolute paths

The kit compares paths when it enforces the file scope. Pass absolute paths (path.resolve(...), or path.join(__dirname, ...)) so a different working directory never changes what the agent can reach.