Configuration
Environment variables, where secrets live, and the Database and GitHub packs.
Two spellings per knob
Every variable has an agent-neutral AGENT_* name, which init and configure-skills write, and a per-agent override under the plugin's prefix (KEVIN_* for agent-kevin; a fork named agent-scout reads SCOUT_* with no code change). The prefixed spelling wins.
Set them per home, in <HOME>/.claude/settings.local.json, under the AGENT_* names. The file's location is what scopes the value to that agent, and every host reads it: Claude Code directly, Codex through the shell env policy generated from it. Never put a KEVIN_* value in a user-level settings file: it is machine-wide and hands every session to one brain.
| Variable | Purpose | Default |
|---|---|---|
KEVIN_HOME | Path to the home. Normally unset: the home is found by walking up for .kevin/. 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 · .kevin/logs/app.log |
AGENT_RUNTIME_DIR | Rename the runtime folder (a bare name, validated) | .kevin |
MARKDOWN_URL | Opener for markdown links on the dashboard | obsidian://open?path={path}&paneType=tab |
If you move knowledge/ or projects/ outside the home after init, add the matching permissions.allow entries to settings.json yourself; the wizard does it only during scaffold.
Where keys live
| Sensitivity | File | Examples |
|---|---|---|
| Secret | <HOME>/.kevin/secrets/.env (and secrets/google/) | SERPAPI_KEY, OPENPAGERANK_API_KEY, PERPLEXITY_API_KEY, GITHUB_TOKEN, AGENT_DB_*, the Google OAuth client |
| Non-secret | <HOME>/.claude/settings.local.json env block | GSC_SITE_URL, AGENT_CODE_PATH, AGENT_GIT_REPOS, and under Claude Code CLAUDE_CODE_OAUTH_TOKEN |
Both are gitignored. The secrets store is deny-gated: Kevin's own shell cannot read it, only the MCP server can. Init owns universal-infra keys (only the optional codebase pair); configure-skills plants a pack's keys as empty placeholders when you activate it. You fill values in your editor, never in chat.
Database pack
database_list, database_schema, and database_query run read-only Postgres queries. Connections are discovered by convention: every AGENT_DB_<NAME> line in the secrets store becomes a connection named <name>.
# <HOME>/.kevin/secrets/.env
AGENT_DB_APP=postgres://user:pass@localhost:5432/app_dev
AGENT_DB_ANALYTICS=postgres://user:pass@host:5432/analyticsEvery query runs inside a BEGIN READ ONLY transaction with a statement timeout and is rolled back, so Postgres rejects any write. For tighter control, point the connection string at a SELECT-only role. database_list reports host, port, and database, never credentials.
database_fork is the one write tool: it clones a local database via CREATE DATABASE <fork> TEMPLATE <source> (pure SQL, no dump files) so you can run destructive schema changes against a scratch copy. It refuses remote hosts, names the fork after the current branch, can repoint an env file at it, and drop: true tears it down. setup-worktree uses it to give a worktree its own database.
GitHub pack
The pr-review skill runs on this pack.
Eleven read-only tools wrapping the gh CLI (brew install gh): PR list, view, inline review comments, diff, checks; run list, view, and failed-step logs; issue list and view; and github_fast_forward, which fast-forwards local default branches during sync. No write subcommands exist.
Auth is a fine-grained, read-only personal access token as GITHUB_TOKEN in the secrets store. configure-skills walks you through minting it: resource owner set to the repos' owner, repository permissions Pull requests · Issues · Metadata · Actions · Contents, all read.
Two permission gotchas
Grant Actions: Read (workflow runs and logs). Do not grant Workflows: despite the name it is write access to the workflow files. Contents: Read is required for git fetch and diffs and grants no push ability. There is no Checks permission for fine-grained tokens, so github_pr_checks returns 403 where CI reports as check runs; read build state from the run tools instead.
When a call omits repo, Kevin resolves it from the origin remote of AGENT_CODE_PATH, then the first AGENT_GIT_REPOS entry. An explicit repo="owner/repo" always wins.