Reference

Environment Variables

All variables are optional unless noted. Sourced from codekepler-npm/src/ via grep 'process.env.' — this list is what the CLI actually reads.

Kepler runtime

Variable	Description
`KEPLER_HOME`	Override the Kepler config directory (default: `~/.kepler`)
`KEPLER_TOKEN`	Auth token — used in CI/CD and headless pipelines
`KEPLER_PRODUCT`	Product variant sent to the backend (`X-Product` header)
`KEPLER_MISSION`	Optional mission tag persisted with the session
`KEPLER_NO_PREFLIGHT`	Skip the onboarding diagnostic on startup (`1` / `true`)
`KEPLER_STATUS_BAR`	Toggle the status bar (`1` / `0`)
`KEPLER_SCRATCH_ROOTS`	Comma-separated writable roots outside the CWD
`KEPLER_PROMPT_BOTTOM_PADDING`	Blank rows below the prompt (default `1`)
`KEPLER_LONG_RUNNING_TIMEOUT_MS`	Override the long-running-tool cutoff
`KEPLER_STAGNATION_DETECTION` / `KEPLER_STAGNATION_THRESHOLD`	Tune stagnation heuristics

Model provider keys (BYOK)

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic direct access
`ANTHROPIC_MODEL`	Default Anthropic model ID
`OPENAI_API_KEY`	OpenAI direct access
`OPENAI_BASE_URL`	Override the OpenAI-compatible endpoint (e.g. self-hosted vLLM)
`OPENROUTER_API_KEY`	OpenRouter (multi-provider routing)
`GEMINI_API_KEY` / `GOOGLE_API_KEY`	Google Gemini access
`BRAVE_API_KEY`	Brave Search (used by the web-search tool)

Logging & debugging

Variable	Description
`DEBUG`	Namespace-scoped debug logging (e.g. `DEBUG=kepler:*`)
`MCP_DEBUG`	Verbose MCP-transport logging
`NO_COLOR`	Disable ANSI colour output

Advanced / rare

Variable	Description
`AGENT_ID`	Identifies sub-agent processes (set automatically)
`CLAUDE_CODE_PERMISSION_MODE`	Legacy fallback for `--permission-mode`
`CLAUDE_CODE_MAX_CONTEXT_TOKENS` / `CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Model I/O caps
`CLAUDE_CODE_STREAMING` / `CLAUDE_CODE_THINKING`	Feature toggles
`CLAUDE_CODE_ENABLE_TASKS`	Enable the built-in task manager
`CLAUDE_CODE_DISABLE_CRON` / `CLAUDE_CODE_DISABLE_TELEMETRY`	Opt-outs
`CLAUDE_CODE_SUBAGENT_MODEL`	Override the model used for sub-agents

Files on Disk

`~/.kepler/` (Global Config)

Path	Purpose
`~/.kepler/auth`	Cached authentication token
`~/.kepler/config.json`	Global preferences (default model, theme, etc.)
`~/.kepler/keys/`	Encrypted API keys for BYOK providers
`~/.kepler/skills/`	User-global installed skills
`~/.kepler/projects/`	Per-project metadata
`~/.kepler/history.jsonl`	Cross-session prompt history
`~/.kepler/state.json`	Current session metadata

`.kepler/` (Project-Local)

Run kepler init in a project to scaffold this folder. Kepler may also create runtime files in .kepler/ as sessions run.

Path	Purpose
`.kepler/KEPLER.md`	Canonical project memory loaded into Kepler context
`.kepler/settings.json`	Project settings, environment entries, permissions, and hook configuration
`.kepler/settings.local.json`	Gitignored local override for personal settings
`.kepler/config.json`	Project policy for context loading, planning, tasks, HITL, and command defaults
`.kepler/project.md`	Additional durable project notes
`.kepler/style.md`	Code style and communication conventions
`.kepler/hitl.md`	Human-in-the-loop approval guidance
`.kepler/trust.json`	Project trust rules used by approval handling
`.kepler/tasks/backlog.md`	Deferred work
`.kepler/tasks/active.md`	Current work in progress
`.kepler/tasks/blocked.md`	Work waiting on input or external state
`.kepler/tasks/done.md`	Completed work
`.kepler/skills/`	Project-local skill bundles
`.kepler/commands/`	Project-local command templates as they become available
`.kepler/approvals.log`	Runtime approval decision log
`.kepler/sessions/`	Runtime session transcripts
`.kepler/reports/`	Runtime mission/report artifacts
`.kepler/index/`	Runtime code-search index cache

Keyboard Shortcuts

Kepler’s REPL uses standard terminal keybindings plus a few extras.

Shortcut	Action
`Esc`	Cancel current execution
`Space`	Pause / resume execution
`↑` / `↓`	Navigate command history
`Ctrl+C`	Cancel current operation / exit
`Ctrl+D`	Exit REPL (same as `/quit`)
`Ctrl+L`	Clear terminal screen
`Ctrl+R`	Search command history (reverse)
`Tab`	Auto-complete commands and file paths
`Ctrl+U`	Clear current input line
`Ctrl+W`	Delete word before cursor
`Ctrl+A`	Move cursor to beginning of line
`Ctrl+E`	Move cursor to end of line

Exit Codes

Code	Meaning
`0`	Success — no errors
`1`	General error — check stderr
`2`	Authentication error — session expired or invalid
`3`	Configuration error — missing or invalid config
`4`	Model error — model not found or unavailable
`5`	Credit error — insufficient credits

Permission Modes

Set with --permission-mode <mode> to control approval behavior.

Mode	Description
`bypassPermissions`	No approval prompts — all tool calls proceed
`acceptEdits`	Auto-approve file edits, prompt for shell commands
`plan`	Block all write operations — read-only planning mode
`auto`	Use tier-based defaults (see risk tiers below)
`dontAsk`	Never prompt — reject anything not auto-approved

Risk Tiers

Every tool call is classified into one of eight tiers.

Tier	Behavior	Examples
`read`	Auto — proceeds silently	`read_file`, `search_code`, `grep`
`sensitive-read`	Prompt required	Reading `.env`, `.pem`, `secrets/*`
`local-edit`	Auto with checkpoint	`edit_file`, `write_file`
`shell-safe`	Auto — proceeds silently	`ls`, `cat`, `pwd`, `git status`
`shell-medium`	Prompt safe (Enter=approve)	`npm install`, `git add`, `pip install`
`shell-dangerous`	Prompt explicit (must type `y`)	`rm -rf`, `chmod -R`, `sudo`
`destructive`	Prompt explicit (must type `y`)	`delete_file`
`network`	Prompt safe (Enter=approve)	`curl`, `wget`, `git clone`

Resume Modes

When resuming a session with --resume, Kepler selects a strategy based on context window size and conversation length.

Strategy	Behavior
`full`	Send the entire conversation transcript
`summary`	Send only a summary of the previous conversation
`summary+tail-10`	Summary + last 10 messages
`summary+tail-20`	Summary + last 20 messages

Event Types

The SSE stream between Kepler and the backend emits these event types:

Event	Direction	Description
`content`	Backend → CLI	Full assistant message
`content_partial`	Backend → CLI	Streaming text delta
`tool_call`	Backend → CLI	Tool invocation request
`tool_result`	CLI → Backend	Tool execution result
`error`	Either	Error event
`complete`	Backend → CLI	Session complete
`timeout`	CLI → Backend	Session timeout
`start`	CLI → Backend	Session start

Tool Catalog

Kepler has 25+ built-in tools. The agent selects and invokes them automatically based on the task.

File I/O

Tool	Description
`read_file`	Read a file with line ranges
`read_files`	Read multiple files at once
`write_file`	Create or overwrite a file
`write_project`	Write multiple files at once
`edit_file`	Search-and-replace edit
`multi_edit`	Multi-file edits
`delete_file`	Delete a file
`ls`	List directory contents

Search

Tool	Description
`search_code`	Semantic search across project code
`search_files`	Regex search across files
`grep`	Fast regex search (ripgrep)
`glob`	Pattern-based file search
`analyze_code`	Get structured analysis of a file
`get_project_overview`	Get project structure overview
`get_file_info`	Get file metadata

Shell

Tool	Description
`bash`	Run shell commands
`tool_search`	Search available tools

Git

Tool	Description
`git_status`	Show git status
`git_diff`	Show git diff

Web

Tool	Description
`web_fetch`	Fetch URLs
`web_search`	Search the web

Agent

Tool	Description
`agent` (explore)	Spawn read-only code explorer
`agent` (review)	Spawn code review agent
`agent` (architect)	Spawn architecture planning agent

Skills

Tool	Description
`skill`	Execute a skill
`skills_list`	List available skills
`skill_view`	View a skill’s details

MCP (Model Context Protocol)

Tool	Description
`read_mcp_resource`	Read MCP resources
`mcp`	MCP tool calls

Scheduling

Tool	Description
`cron_create`	Create a cron job
`cron_delete`	Delete a cron job
`cron_list`	List cron jobs

Other

Tool	Description
`ask_user`	Ask the user a question
`send_message`	Send a message
`enter_worktree`	Enter a worktree
`exit_worktree`	Exit a worktree
`notebook_edit`	Edit Jupyter notebooks
`todo_write`	Write task items
`lsp`	Language server protocol
`remote_trigger`	Remote trigger

File Structure for the Kepler NPM Package

kepler/
├── bin/
│   └── cli.js            # Entry point for the `kepler` command
├── src/
│   ├── terminal/
│   │   ├── main.mjs      # CLI entry, subcommand dispatch
│   │   ├── repl.mjs      # REPL loop, command parsing
│   │   ├── agents.mjs    # Built-in agent definitions (explore, review, architect)
│   │   ├── analytics.mjs # Sessions, stats, history subcommands
│   │   ├── init.mjs      # `kepler init` — scaffold .kepler/
│   │   └── skills.mjs    # `kepler skills` — skill management
│   ├── agents/           # Agent team orchestration
│   ├── auth/             # Browser auth flow (bahulam.ai) + config
│   ├── config/           # CLI args, env, settings, memory, hooks
│   ├── context/          # AST parser, BM25 retriever, skeleton, symbol indexer
│   ├── core/             # Central logic (30+ modules)
│   ├── hooks/            # Hook engine
│   ├── mcp/              # MCP client + transports (SSE, WebSocket, SHTTP)
│   ├── onboarding/       # Preflight diagnostics
│   ├── permissions/      # Command classifier, injection check, path check, sandbox
│   ├── plugins/          # Plugin loader
│   ├── skills/           # Skill installer, loader, runner
│   ├── state/            # Orbit state, verbosity
│   ├── telemetry/        # Telemetry index
│   ├── tools/            # 25+ built-in tool implementations
│   └── ui/               # Approval, banner, commands, dock, formatter, icons
├── pulse/                # Kepler Pulse Next.js analytics dashboard
└── package.json

Data Flow

┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Terminal     │────▶│  Kepler CLI      │────▶│  API Gateway     │
│  (REPL)       │     │  (Agent)         │     │  (Platform)      │
└──────────────┘     └────────┬─────────┘     └────────┬─────────┘
                              │                        │
                              ▼                        ▼
                       ┌──────────────┐       ┌──────────────────┐
                       │  Sub-Agents   │       │  LLM APIs        │
                       │  Explorer     │       │  (OpenRouter)    │
                       │  Planner      │       │  (Anthropic)     │
                       └──────────────┘       │  (OpenAI)        │
                                              │  (Google)        │
                                              └──────────────────┘

You type a request in the REPL
Kepler’s orchestrator analyzes the request
If needed, sub-agents explore the codebase and plan the approach
The orchestrator generates code changes via tool calls
Each tool call is classified by risk tier and approved accordingly
Changes are applied to your files
Results are reported back in the terminal

Glossary

Term	Definition
BM25	Best Matching 25 — text retrieval algorithm used for project indexing
BYOK	Bring Your Own Key — use your own API key instead of the platform default
BYOM	Bring Your Own Model — connect a custom model endpoint
Checkpoint	A save point recorded before auto-approved edits, enabling undo
Credit	Unit of billing on the platform default plan
Explorer	Sub-agent that reads files and searches code (read-only)
Freeswim	Mode that skips all approval prompts
Gateway	Provider routing layer (platform, OpenRouter, Anthropic, etc.)
Headless	Non-interactive mode for automation and benchmarks
HITL	Human-in-the-loop — review-and-confirm workflow
Local	Mode that bypasses the backend and calls LLM APIs directly
MCP	Model Context Protocol — connect external tools and data sources
Orchestrator	The main agent that coordinates sub-agents and tool calls
Planner	Sub-agent that designs architecture and implementation approach
REPL	Read-Eval-Print Loop — Kepler’s interactive terminal interface
Resume	Continue a previous session with context preservation
Skill	A portable SKILL.md bundle with instructions and references
Sub-agent	A specialized agent (explorer, planner, etc.) that handles a specific role
Trust	Auto-approval granted for a specific tool from a specific agent in a session

Troubleshooting