A general-purpose AI agent harness.

meka is a general-purpose AI agent harness: it wraps a large language model with a tool set, working memory, persistent sessions, a permission model, and several front-ends (an interactive REPL, one-shot commands, an editor agent via ACP, and an HTTP service). Bring a provider (Claude or OpenAI, API key or subscription) and meka turns it into an agent that reads and edits files, runs commands, searches the web, calls MCP servers, and delegates to sub-agents to accomplish real tasks.

Supported providers:

• OpenAI API: bring your own API key. Also works with any OpenAI-compatible endpoint.
• OpenAI Codex: authenticate with a ChatGPT subscription.
• Claude API: bring your own API key.
• Claude OAuth: authenticate with a Claude subscription.

Download a pre-built binary from GitHub Releases, or install with Cargo:

cargo install --locked --git https://github.com/k4yt3x/meka.git

Add a provider profile with meka provider add. It runs the OAuth login (or prompts for an API key), stores the secret in the database, and writes the profile to ~/.config/meka/config.toml:

meka provider add work --type claude-oauth --model claude-opus-4-6

The profile pins a backend type (openai-api, openai-codex, claude-api, or claude-oauth) plus a model. Add several profiles and switch with meka provider use <name> or --provider <name>. For an OpenAI-compatible endpoint like OpenRouter, set --base-url:

meka provider add openrouter --type openai-api --model anthropic/claude-opus-4.6 \
    --base-url https://openrouter.ai/api/v1

Run meka and start typing. Press Shift+Tab to cycle permissions (none, read, ask, write):

meka [r] > find all TODO comments in this project
meka [w] > install and start nginx

See the documentation for the full usage guide.

The same agent core is available through several interfaces:

• CLI REPL: an interactive prompt in your terminal.
• ACP: makes meka work inside editors like Zed via the Agent Client Protocol.
• HTTP API: embed meka as an agent backend in your own apps, bots, and services.

The agent has access to the following built-in tools:

• Shell: execute commands and read their output
• ReadFile / WriteFile / EditFile: read, create, and modify files
• FindFiles: find files by name or glob pattern
• SearchContents: search file contents with regex (powered by ripgrep)
• FetchUrl: fetch and read web page content
• WebSearch: search the web for up-to-date information
• Scratchpad: session-scoped working memory for intermediate results
• Todo: structured task tracking for multi-step work, with live progress display
• SpawnAgent: delegate research tasks to a read-only sub-agent
• Skill: load reusable prompt templates on demand
• RenderImage: render an image into the conversation for vision-capable models
• MCP resources / prompts: read or render content from configured MCP servers

Long-output tools support an optional scratchpad parameter to save output directly to the scratchpad.

The prompt indicator shows the current permission mode. Press Shift+Tab to cycle between modes:

• [n] none: no tools available, text-only responses
• [r] read: read-only tools (file reading, searching, web, sandboxed shell)
• [a] ask: all tools available, but each call requires user approval
• [w] write: all tools enabled, including shell execution and file writes

Conversations are persisted in a local SQLite database and can be resumed:

• meka -c continues the last session
• meka -c <UUID> resumes a specific session by ID
• meka session list lists past sessions
• meka session delete <UUID> deletes sessions
• meka session export <UUID> exports a session as Markdown
• meka history list / meka history clear view or clear REPL input history
• /export exports the current session from within the shell
• /compact summarizes and compacts the session history

• Extended/adaptive thinking: enabled by default for Claude models that support it
• Syntax-highlighted output: bat-powered markdown rendering with code block highlighting
• Auto-compact: automatically compacts the conversation when approaching the context limit
• MCP support: extend the agent with tools from external MCP servers
• Skills: load reusable prompt templates from ~/.config/meka/skills/

Prefix input with ! to execute a command directly, bypassing the LLM:

meka [r] > !uname -a
meka [r] > !docker ps

Type exit, quit, or press Ctrl+D to leave the shell.

AI tools were used to assist the design and implementation of this project. All design decisions were made by humans, and every change was reviewed and approved by a human maintainer.

This project is licensed under the MIT License.
Copyright 2026 K4YT3X.