Quick Start

1. Add a Provider

Before the first run, configure a provider profile. meka provider add runs the right credential flow (OAuth login or API-key prompt) and writes the profile to ~/.config/meka/config.toml:

# Claude Code subscription (OAuth)
meka provider add work --type claude-subscription --model claude-opus-5

# or a Claude API key
meka provider add work --type anthropic-messages --model claude-opus-5

# or OpenAI
meka provider add work --type openai-chat-completions --model gpt-5.6-sol

add prompts for any of --type / --model you omit, acquires the secret (browser OAuth for claude-subscription / chatgpt-subscription, an API-key prompt otherwise), stores it in the database, and makes the profile the default. Add more profiles later and switch with meka provider use <name> or the per-run --provider <name> flag.

If you launch meka with no provider configured, it errors and tells you to run meka provider add. See Configuration for all options and the full meka provider reference.

2. Start Using meka

After setup, you will see a prompt:

meka [r] >

The [r] indicates read permission mode (the default). The agent can read files, search, and run shell commands in a sandbox that blocks writes. It cannot modify your files.

3. Ask It Something

meka [r] > what files are in the current directory?

The agent will use the find_files tool to list files and describe them.

4. Enable Workspace Mode

Press Shift+Tab to cycle the permission to workspace, where the agent may write inside your working directory:

meka [w] >

Now it can modify files too, and its shell may write inside the same boundary:

meka [w] > create a file called hello.txt with the text "hello world"

5. One-Shot Mode

For quick tasks without entering the interactive shell:

meka --oneshot "what is my current working directory?"

The process exits after the agent responds. Without --oneshot the same prompt runs as the first turn and then drops you into the interactive shell.

6. Continue a Previous Session

To pick up where you left off, continue the last session:

meka -c

Or resume a specific session by its UUID:

meka -r 550e8400-e29b-41d4-a716-446655440000

See Sessions for more details.