A dead simple CLI agent for Linux & macOS

Meet Wisemonkey
Your Hackable Harness

A simple, open and extensible AI agent for the terminal. Connect to any OpenAI, Anthropic or Ollama-compatible endpoint and get session management, persistent memory, vector search, native and MCP tools, skills, external tool hooks and container support — all in one sleek CLI.

Get Started ↓ Explore Features →

Interactive Demo

See It In Action

A simulated Wisemonkey session — the welcome screen you see on first launch, followed by example prompts showcasing natural-language control over tools, memory, sessions, providers, and MCP servers.

wisemonkey — wisemonkey

  ╻ ╻╻┏━┓┏━╸┏┳┓┏━┓┏┓╻╻┏ ┏━╸╻ ╻
  ┃╻┃┃┗━┓┣╸ ┃┃┃┃ ┃┃┗┫┣┻┓┣╸ ┗┳┛
  ┗┻┛╹┗━┛┗━╸╹ ╹┗━┛╹ ╹╹ ╹┗━╸ ╹   v2026.10.15 commit: 09cd2a5

✓ Up to date (last check: 6s)

⇒ Session restored: 'mysession'
location:      ~/.local/share/wisemonkey/sessions/mysession
working dir:   ~/Projects/wisemonkey
created:       139d 0h 44m 30s
last accessed: 5m 20s
context:       36299 tokens (16.50% of 220000 budget)

Previous conversation (last 1 exchange, truncated)

User:

Summarise what changed in this repo today and list anything I left unfinished.

Assistant:

Five files touched this morning, mostly in src/cache. Two loose ends: the eviction path still has no test, and the retry backoff is hard-coded. Want me to open an issue for those? (continued)

Previous conversation stats: 36299 tks - 16.50% of 220000 budget

/slash commands

!shell command, attach output to context

@reference file/directory, attach to context

?show help

/configureconfigure the agent interactively

Capabilities

Built for Power Users

Multi-Provider Support

Connect to OpenAI, Anthropic, Ollama, LM Studio, or any OpenAI-compatible router. Per-endpoint API keys resolve from an ordered chain — switch providers without moving a single key.

Persistent Memory

Session-scoped chat history, user profiles and notes that survive restarts. A rolling window and token-cap compaction keep the context bounded, with everything trimmed archived instead of lost.

Vector Search (RAG)

Embed PDFs and documents into a per-session vector store with /embed. The agent retrieves relevant context on demand.

MCP Integration

Connect to Model Context Protocol servers over stdio, HTTP or SSE for filesystem access, GitHub, databases, and more. Standard mcp.json format.

28 Built-In Tools

Files, search, shells and background jobs, images, web, memory, plans, screenshots. Register more at runtime — MCP tools are auto-discovered and injected.

Streaming & Reasoning

Real-time token streaming with per-provider reasoning effort and a live token counter — the status line shows the turn's delta, prompt tokens and cost.

External Tool Hooks

Guard programs run before every tool call, using the Claude Code / Codex hook protocol. Plug in dcg or any existing hook to allow, ask or deny — in the REPL and in daemon mode.

Container Ready

Run the agent with wmkc: no Python or uv on the host. It runs as your user, mounts only the workspace, config and data, and needs no capabilities.

Mid-Turn Steering

Type while the model is working and your line is injected at the next tool-call seam — a real correction mid-turn, not a new one. Plus client/server mode for shared sessions.

Get Started

Up and Running in Seconds

# One-line installation (adds `wmk` to ~/.local/bin)

$ curl -fsSL https://codeberg.org/langurmonkey/wisemonkey/raw/branch/master/install.sh | sh

# Interactive first-time configuration

$ wmk --onboard

# Run the agent

$ wmk [session-name]

# Install uv

$ curl -LsSf https://astral.sh/uv/install.sh | sh

# Run straight from PyPI — no install step

$ uvx wisemonkey --onboard

# Run the agent

$ uvx wisemonkey [session-name]

# No Python or uv on the host — build the image once, then run

$ cd ~/my-project && wmkc

# A named session — same arguments as wmk

$ wmkc my-project

# Rebuild after editing the agent

$ WMKC_REBUILD=1 wmkc

# Clone repository

$ git clone https://codeberg.org/langurmonkey/wisemonkey.git && cd wisemonkey

# Install dependencies

$ uv sync

# Configure and run

$ uv run wmk --onboard

$ uv run wmk [session-name]

Configuration

One File, Total Control

On first run, Wisemonkey creates ~/.config/wisemonkey/config.yaml with sensible defaults. Works with any OpenAI-compatible endpoint out of the box — and a session can override it with its own copy.

model:

# Provider: openai, ollama, lmstudio, anthropic, generic (OpenAI-compatible)

provider: generic

name: deepseek-v4.1-flash

base_url: https://router.example.com/v1

# Name only, never the key itself -- config.yaml stays safe to share

api_key_env: OPENROUTER_API_KEY

temperature: 0.8

pricing: { input: 0.3, output: 1.2 } # per M tokens; cost is omitted if unset

thinking:

# none, minimal, low, medium, high, xhigh, max

effort: medium

display: true

embedding:

name: qwen/qwen3-embedding-0.6b-gguf

base_url: http://127.0.0.1:1234/v1

agent:

max_turns: 50

max_chat_history: 220000

markdown_stream: true

steer_midturn: true

tool_slow_threshold: 1.0

soul_file: SOUL.md

skills: true

context_files:

- AGENTS.md

vi_mode: false

# Guard programs run around every tool call (agent.hooks).

# The protocol is Claude Code / Codex compatible: JSON on stdin,

# {"hookSpecificOutput": {"permissionDecision": ...}} on stdout.

agent:

hooks:

# Runs before the tool. A deny (or a declined ask) is

# fed back to the model as a tool error; the turn continues.

pre_tool_use:

- matcher: "run_command|spawn" # regex over tool names

hooks:

- type: command

command: /usr/local/bin/dcg # absolute path

timeout: 5 # seconds

honor_unsafe: false # if true, skipped when /unsafe is on

# Audit hooks run after the tool; their output is ignored.

post_tool_use: []

{

"mcpServers": {

"filesystem": {

"command": "npx",

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

"github": {

"type": "http", // stdio | http | sse

"url": "https://api.githubcopilot.com/mcp/"

}

# Use /mcp edit to modify, /mcp tools to list

# Resolved per provider, first non-empty wins:

# model.api_key_env → WM_API_KEY_<PROVIDER> → OPENAI_API_KEY → WM_API_KEY

OPENROUTER_API_KEY=sk-or-...

OPENCODE_API_KEY=sk-oc-...

WM_API_KEY_ANTHROPIC=sk-ant-...

# Loaded automatically by python-dotenv; searched in order:

# ./.env → ~/.config/wisemonkey/.env → ~/.env

OpenAI, Anthropic, and Ollama APIs

LM Studio, Claude, Ollama, OpenWebUI, or your own server. Just set base_url.

Reasoning Control

Set model.thinking.effort to none, minimal, low, medium, high, xhigh or max. Each provider translates the level to its own dialect; visibility is toggled with display.

Tool Hooks

Declare agent.hooks guards that inspect every tool call. A hook that cannot start fails open; one that hangs or misbehaves fails closed.

Per-Session Config

A session loads <session_dir>/config.yaml first and falls back to the global config, so sessions can diverge freely.

vi Mode & Soul File

Enable vi_mode for vim-style editing (v opens your editor), and give the agent an identity with a global or workspace SOUL.md.

Standard `mcp.json`

Edit MCP servers in a format you are comfortable with — stdio, HTTP or SSE.

By the Numbers

Wisemonkey at a Glance

AI Providers

∞

MCP Servers

Built-In Tools

Config Headaches

Meet WisemonkeyYour Hackable Harness