Project Structure

Everything that defines your agent lives in your repo root. The runtime reads these files at startup and watches for changes during development.

my-agent/
├── amodal.json                  ← root config: name, models, sandbox, MCP
├── connections/                 ← REST APIs and MCP servers
│   ├── slack/
│   │   ├── spec.json            ← API source, auth, entities, sync config
│   │   ├── access.json          ← field restrictions, action tiers, scoping
│   │   ├── surface.md           ← (optional) endpoint documentation
│   │   ├── entities.md          ← (optional) entity definitions
│   │   └── rules.md             ← (optional) business rules
│   ├── internal-api/
│   │   ├── spec.json
│   │   └── access.json
│   └── github/                  ← MCP connection (no access.json needed)
│       └── spec.json
├── skills/                      ← Markdown reasoning frameworks
│   └── triage/
│       └── SKILL.md
├── knowledge/                   ← Domain knowledge documents
│   ├── environment.md
│   └── baselines.md
├── tools/                       ← Custom tool handlers
│   └── create_ticket/
│       ├── tool.json            ← (optional) metadata, parameters, confirmation
│       └── handler.ts           ← handler code
├── stores/                      ← Persistent data store schemas
│   └── active-alerts.json
├── pages/                       ← React UI views (dashboards, briefs)
│   ├── ops-dashboard.tsx
│   └── morning-brief.tsx
├── automations/                 ← Scheduled or trigger-based runs
│   └── daily-digest.json
├── evals/                       ← Test cases for agent quality
│   └── triage-accuracy.md
├── agents/                      ← subagents + built-in overrides
│   ├── explore/                 ← override: replaces default explore agent
│   │   └── AGENT.md
│   ├── compliance-checker/      ← custom subagent
│   │   └── AGENT.md
│   └── vendor-lookup/           ← custom subagent
│       └── AGENT.md
└── .amodal/
    └── store-data/              ← PGLite data directory (gitignored)

Config Reference

File/Directory	What It Does	Docs
`amodal.json`	Agent identity, models, sandbox, MCP servers	amodal.json
`connections/`	REST API and MCP server connections	Connections
`skills/`	Expert reasoning frameworks	Skills
`knowledge/`	Domain knowledge documents	Knowledge Base
`tools/`	Custom tool handlers with code	Tools
`stores/`	Persistent data store schemas	Stores
`pages/`	React UI views (dashboards, briefs, detail screens)	Pages
`automations/`	Scheduled/triggered agent runs	Automations
`evals/`	Test cases and assertions	Evals
`agents/`	Custom subagents + built-in agent overrides	Agents
MCP servers	Defined as connections or in `amodal.json`	MCP Servers

Hot Reload

During amodal dev, the runtime watches all config files for changes with 300ms debounce. Edit any file and the agent picks up changes instantly — no restart needed.