Project structure
How the SDK discovers config, skills, agents, and providers from your project.
The .theokit/ directory
The SDK reads several things from a .theokit/ folder at your project root. None of these are required — the SDK has sensible defaults — but they unlock features as you grow:
my-project/
├── .theokit/
│ ├── agents/ # Named agents (markdown + YAML frontmatter)
│ ├── skills/ # Invokable skills, one .md per skill
│ ├── personalities/ # Persona presets, project-scoped
│ ├── plugins/ # Local plugin definitions (.js or .ts)
│ ├── cron/jobs.json # Scheduled jobs persisted across restarts
│ ├── mcp.json # MCP server config (stdio + HTTP servers)
│ ├── hooks.json # Hook handlers
│ ├── memory/ # SQLite + vec indexes (if memory.enabled)
│ └── THEO.md # Project-level instructions (auto-discovered context)
├── CLAUDE.md # Auto-discovered context file (multi-tool standard)
├── AGENTS.md # Auto-discovered context file
├── GEMINI.md # Auto-discovered context file
└── .cursor/rules/ # Cursor-style rules (MDC format)The SDK walks up to the nearest .git directory when resolving these — same conventions as git config and most modern dev tools.
User-level overrides
Anything in .theokit/ also has a global counterpart at ~/.theokit/:
| File | Project-level | User-level | Merge order |
|---|---|---|---|
mcp.json | .theokit/mcp.json | ~/.theokit/mcp.json | Project entries override user entries by key |
hooks.json | .theokit/hooks.json | ~/.theokit/hooks.json | Concatenated |
agents/*.md | .theokit/agents/ | ~/.theokit/agents/ | Project wins on name collision |
personalities/*.md | .theokit/personalities/ | ~/.theokit/personalities/ | Project wins on collision |
Environment variables
The SDK reads a small set of env vars at runtime. All THEOKIT_* vars are SDK-specific; provider keys (OPENAI_API_KEY, etc.) follow each provider's convention.
| Env var | Purpose | Default |
|---|---|---|
THEOKIT_API_KEY | Cloud runtime API key (PaaS pre-release) | unset |
THEOKIT_API_BASE_URL | Override cloud endpoint (testing) | unset |
THEOKIT_HOME | Override ~/.theokit/ location | ~/.theokit/ |
THEOKIT_REDACT_SECRETS | "0" to disable secret-redaction at output boundaries | enabled |
OPENAI_API_KEY / OPENROUTER_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY | Provider auth | unset |
AWS_BEARER_TOKEN_BEDROCK or AWS credential chain | Bedrock auth | unset |
GOOGLE_APPLICATION_CREDENTIALS or GOOGLE_CLOUD_PROJECT | Vertex auth | unset |
OLLAMA_HOST / LMSTUDIO_HOST / LLAMACPP_HOST | Local provider base URLs | localhost defaults |
Context files (auto-loaded)
The SDK auto-discovers and merges these context files into every agent's system prompt (in priority order):
.theokit/THEO.md— project-specific instructionsCLAUDE.md— Claude Code conventionAGENTS.md— multi-tool standardGEMINI.md— Gemini Code Assist convention.cursor/rules/*.mdc— Cursor rules (filtered by glob)
You don't import these — the SDK finds them via walk-up-to-git-root. See the Configuration concept for details.
Where to put what
| You want to... | Put it in... |
|---|---|
Define a named agent (one .md per agent) | .theokit/agents/my-agent.md |
| Define a skill the agent can invoke | .theokit/skills/my-skill.md |
| Configure MCP servers | .theokit/mcp.json |
| Override default model per environment | env vars or model: { id } in code |
| Pin tool whitelist for a persona | .theokit/personalities/coder.md |
| Schedule a cron job | .theokit/cron/jobs.json (auto-created) |
Next
Pick a provider and configure auth, then build your first real agent.