Getting Started

Getting Started

Install

Install Kepler globally via npm:

npm i -g @axplusb/kepler

You can also install a specific version:

npm i -g @axplusb/kepler@latest

Or run without installing using npx:

npx @axplusb/kepler@latest

Sign In

Run Kepler in any project directory:

kepler

On first launch, Kepler opens a browser window and redirects you to bahulam.ai to authenticate. If you’re in a headless environment, it will print a URL you can open manually.

→ Opening browser for authentication...
→ If the browser didn't open, visit:
  https://bahulam.ai/auth/cli?code=...

You can also sign in explicitly at any time:

kepler login

Once authenticated, your session is cached locally and you won’t need to sign in again on that machine.

Your First Turn

After signing in, you’ll see the Kepler REPL prompt:

> _

Try a simple task:

> what does this project do?

Kepler will:

  1. Explore the project structure
  2. Read key configuration files
  3. Summarize what it found

For a code change, try:

> add a .gitignore file

Kepler plans the change, shows you a diff, applies it, and reports the result.

The .kepler/ Folder

Run kepler init in a project to scaffold the project-local .kepler/ folder:

kepler init

The canonical project memory file is .kepler/KEPLER.md. Use it for durable project facts that Kepler should read on every turn, such as the stack, test command, lint command, key directories, code style, and critical rules.

kepler init creates these hand-editable files:

PathPurpose
.kepler/KEPLER.mdCanonical project memory loaded into Kepler context
.kepler/settings.jsonProject settings, environment entries, permissions, and hook configuration
.kepler/config.jsonProject policy for context loading, planning, tasks, HITL, and command defaults
.kepler/project.mdAdditional durable project notes
.kepler/style.mdCode style and communication conventions
.kepler/hitl.mdProject-specific human approval guidance
.kepler/tasks/Markdown task board files: backlog.md, active.md, blocked.md, and done.md
.kepler/skills/Project-local skill bundles
.kepler/commands/Project-local command templates as they become available
.kepler/trust.jsonProject trust rules for approvals

Kepler may also write runtime files such as .kepler/approvals.log, .kepler/sessions/, and .kepler/reports/. The scaffolded .kepler/.gitignore keeps local-only runtime files out of source control.

Resuming a Session

Continue where you left off:

# Resume the most recent session
kepler --resume
 
# Resume a specific session
kepler --resume session_abc123

Kepler automatically selects the best context strategy (full transcript, summary, or summary + recent messages) based on the model’s context window.

Next Steps

WelcomeCommands