Configuration
The settings a home reads, the file each one goes in, and where every key lives.
A home is configured by three files inside it. Every host reads them: Claude Code directly, Codex through the wiring generated from them.
| File | Holds | Git |
|---|---|---|
<HOME>/.claude/settings.local.json | This machine's settings, in its env block | Ignored |
<HOME>/.claude/settings.json | Permissions: which tools run without asking, which always ask, which are denied | Safe to commit; it holds no secrets |
<HOME>/.state/secrets/.env | Keys, tokens and connection strings | Ignored |
The AGENT_* variables
Every setting has one AGENT_* name, the only one the plugin reads. The names carry no agent's name, because several homes can share one plugin install. Set a variable in that home's settings.local.json:
{ "env": { "AGENT_CODE_PATH": "/Users/you/Developer/acme" } }| Variable | Purpose | Default |
|---|---|---|
AGENT_HOME | Path to the home. Normally unset: the home is found by walking up for .state/. Useful as a one-off prefix for the CLI outside a home | resolved from the launch dir |
AGENT_TIMEZONE | IANA timezone for dates | system timezone |
AGENT_HOME_TIMEZONE | Home-base timezone; when it differs from the live one, session context flags you as traveling | unset |
AGENT_KNOWLEDGE · AGENT_PROJECTS · AGENT_REPORTS | Move those directories elsewhere (a synced folder, another repo) | under the home |
AGENT_CODE_PATH | Your primary codebase. Grounds code tasks and surfaces its git activity in session context | none |
AGENT_GIT_REPOS | Comma-separated extra repos shown in the SessionStart git block | derived from AGENT_CODE_PATH |
AGENT_LOG_LEVEL · AGENT_LOG_FILE | debug · info · warn · error; off disables file output | info · .state/logs/app.log |
MARKDOWN_URL | An app to open the dashboard's file links in, as a URL with a {path} placeholder | empty: plain file links |
Two more are written for you and are not set by hand:
| Variable | Written by | Means |
|---|---|---|
AGENT_HOME_GIT_DIR | The history skill | Where a synced home keeps its history |
AGENT_SUBSCRIPTION | The token file in Billing per agent | This session started on the agent's own Claude subscription |
Setup writes AGENT_HOME_TIMEZONE, and AGENT_CODE_PATH and AGENT_GIT_REPOS when you give it a code path.
Never set these machine-wide
Keep per-home values (the home, code path, repos, databases) out of a user-level settings file and out of your shell profile. Both are machine-wide, so one value reaches every agent home on the machine. AGENT_HOME there outranks the folder you launch from, so every session lands in one brain.
If you move knowledge/ or projects/ outside the home after setup, add the matching permissions.allow entries to settings.json yourself. The wizard does it only when it first creates the home.
Where keys live
| Sensitivity | File | Examples |
|---|---|---|
| Secret | <HOME>/.state/secrets/.env, with secrets/google/ and secrets/slack/ beside it | API keys, GitHub tokens, database connection strings, the Google OAuth client, your Slack sign-in |
| Secret | <HOME>/.state/secrets/.env.claude.json | An agent's own Claude subscription token, which Claude Code reads when started with agent (Billing per agent) |
| Not secret | <HOME>/.claude/settings.local.json, env block | Site addresses, usernames, a Slack app's Client ID, the AGENT_* variables |
- Both files are ignored by git.
- The agent cannot read the secrets store. Its own shell is denied; only the MCP server reads it.
- You type key values in your editor, never in chat.
configure-skillsmakes sure the secrets file exists and tells you which lines to add.
More on what stays private: Privacy.
Keys by pack
Each pack's page has the steps for getting its keys.
| Pack | In .state/secrets/.env | In settings.local.json env |
|---|---|---|
| GitHub | GITHUB_TOKEN_<OWNER> per repo owner, GITHUB_TOKEN as catch-all | |
| Database | AGENT_DB_<NAME> per database | |
| Browser | PERPLEXITY_API_KEY | |
| SEO | SERPAPI_KEY, OPENPAGERANK_API_KEY; the Google OAuth client in secrets/google/ | GSC_SITE_URL |
| Slack | Your sign-in tokens in secrets/slack/, written by bun "<plugin root>/src/cli.ts" slack auth | AGENT_SLACK_CLIENT_ID |
| Helpdesk | SUPPORTCANDY_APP_PASSWORD[_<NAME>], PYLON_API_TOKEN[_<NAME>] | SUPPORTCANDY_URL[_<NAME>], SUPPORTCANDY_USERNAME[_<NAME>] |
| App Store, Xcode, API | None | None |