AgentLayer▸docs
Run it

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.

FileHoldsGit
<HOME>/.claude/settings.local.jsonThis machine's settings, in its env blockIgnored
<HOME>/.claude/settings.jsonPermissions: which tools run without asking, which always ask, which are deniedSafe to commit; it holds no secrets
<HOME>/.state/secrets/.envKeys, tokens and connection stringsIgnored

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" } }
VariablePurposeDefault
AGENT_HOMEPath 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 homeresolved from the launch dir
AGENT_TIMEZONEIANA timezone for datessystem timezone
AGENT_HOME_TIMEZONEHome-base timezone; when it differs from the live one, session context flags you as travelingunset
AGENT_KNOWLEDGE · AGENT_PROJECTS · AGENT_REPORTSMove those directories elsewhere (a synced folder, another repo)under the home
AGENT_CODE_PATHYour primary codebase. Grounds code tasks and surfaces its git activity in session contextnone
AGENT_GIT_REPOSComma-separated extra repos shown in the SessionStart git blockderived from AGENT_CODE_PATH
AGENT_LOG_LEVEL · AGENT_LOG_FILEdebug · info · warn · error; off disables file outputinfo · .state/logs/app.log
MARKDOWN_URLAn app to open the dashboard's file links in, as a URL with a {path} placeholderempty: plain file links

Two more are written for you and are not set by hand:

VariableWritten byMeans
AGENT_HOME_GIT_DIRThe history skillWhere a synced home keeps its history
AGENT_SUBSCRIPTIONThe token file in Billing per agentThis 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

SensitivityFileExamples
Secret<HOME>/.state/secrets/.env, with secrets/google/ and secrets/slack/ beside itAPI keys, GitHub tokens, database connection strings, the Google OAuth client, your Slack sign-in
Secret<HOME>/.state/secrets/.env.claude.jsonAn 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 blockSite 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-skills makes 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.

PackIn .state/secrets/.envIn settings.local.json env
GitHubGITHUB_TOKEN_<OWNER> per repo owner, GITHUB_TOKEN as catch-all
DatabaseAGENT_DB_<NAME> per database
BrowserPERPLEXITY_API_KEY
SEOSERPAPI_KEY, OPENPAGERANK_API_KEY; the Google OAuth client in secrets/google/GSC_SITE_URL
SlackYour sign-in tokens in secrets/slack/, written by bun "<plugin root>/src/cli.ts" slack authAGENT_SLACK_CLIENT_ID
HelpdeskSUPPORTCANDY_APP_PASSWORD[_<NAME>], PYLON_API_TOKEN[_<NAME>]SUPPORTCANDY_URL[_<NAME>], SUPPORTCANDY_USERNAME[_<NAME>]
App Store, Xcode, APINoneNone

On this page