Langrepl

Interactive terminal CLI for building and running LLM agents. Built with LangChain, LangGraph, Prompt Toolkit, and Rich.

CLI Mode

https://github.com/user-attachments/assets/f9573310-29dc-4c67-aa1b-cc6b6ab051a2

AG-UI Mode

https://github.com/user-attachments/assets/3666d330-154c-4443-902c-8640c66a7d62

Table of Contents

• Features
• Prerequisites
• Installation
  • From GitHub
  • From PyPI
  • From Source
  • Environment Variables
  • CLI Flags
• Quick Start
  • Interactive Chat Mode
  • One-Shot Mode
  • LangGraph Server Mode
  • AG-UI Server Mode
• Interactive Commands
  • Conversation Management
  • Configuration
  • Utilities
• Usage
  • Agents
  • Custom Prompts
  • LLMs
  • Checkpointers
  • Sub-Agents
  • Custom Tools
  • Skills
  • Server
  • MCP Servers
  • Tool Approval
  • Sandboxes (Beta)
• Development
• License

Features

• Deep Agent Architecture - Planning tools, virtual filesystem, and sub-agent delegation for complex multi-step tasks
• LangGraph Server Mode - Run agents as API servers with LangGraph Studio integration for visual debugging
• AG-UI Server Mode - Expose agents via the AG-UI protocol (SSE streaming) for frontend integration with CopilotKit and other AG-UI clients
• Multi-Provider LLM Support - OpenAI, Anthropic, Google, AWS Bedrock, Ollama, DeepSeek, ZhipuAI, Moonshot AI (Kimi), and local models (LMStudio, Ollama)
• Multimodal Image Support - Send images to vision models via clipboard paste, drag-and-drop, or absolute paths
• Extensible Tool System - File operations, web search, terminal access, grep search, and MCP server integration
• Skill System - Modular knowledge packages that extend agent capabilities with specialized workflows and domain expertise
• Persistent Conversations - SQLite-backed thread storage with resume, replay, and compression
• User Memory - Project-specific custom instructions and preferences that persist across conversations
• Human-in-the-Loop - Configurable tool approval system with regex-based allow/deny rules
• Cost Tracking (Beta) - Token usage and cost calculation per conversation
• MCP Server Support - Integrate external tool servers via MCP protocol with optional stateful connections
• Sandbox (Beta) - Secure isolated execution for tools with filesystem, network, and syscall restrictions

Prerequisites

macOS and Linux only — Windows is not supported.

• Python 3.13+ — Older versions will fail to install. Check with python3 --version
• uv — Fast Python package manager (install instructions)
• ripgrep (rg) — Required for code search and directory structure:
  • macOS: brew install ripgrep
  • Ubuntu/Debian: sudo apt install ripgrep
  • Arch Linux: sudo pacman -S ripgrep
• fd — Required for file/directory completion with @:
  • macOS: brew install fd
  • Ubuntu/Debian: sudo apt install fd-find && sudo ln -s $(which fdfind) /usr/bin/fd
  • Arch Linux: sudo pacman -S fd
• tree — Required for file system visualization:
  • macOS: brew install tree
  • Ubuntu/Debian: sudo apt install tree
  • Arch Linux: sudo pacman -S tree
• bubblewrap (Linux only, optional) — Required for sandbox feature:
  • Ubuntu/Debian: sudo apt install bubblewrap
  • Arch Linux: sudo pacman -S bubblewrap
• Node.js & npm (optional) — Required for MCP servers that run via npx and for the AG-UI chat UI
• pnpm (optional) — Required for the AG-UI chat UI (ui/)
  • npm install -g pnpm or corepack enable

Installation

The .langrepl config directory is created in your working directory (or use -w to specify a location). Aliases: langrepl or lg

Use --python 3.13 with uvx and uv tool install so uv builds the isolated tool environment with a supported Python version.

From GitHub

Recommended when you want the latest fixes from main before they are published to PyPI.

Quick try (no installation):

uvx --python 3.13 --from git+https://github.com/midodimori/langrepl langrepl
uvx --python 3.13 --from git+https://github.com/midodimori/langrepl langrepl -w /path

Install globally:

uv tool install --python 3.13 git+https://github.com/midodimori/langrepl

Then run from any directory:

langrepl              # or: lg
langrepl -w /path     # specify working directory

Upgrading: Re-run uv tool install --force --python 3.13 git+https://github.com/midodimori/langrepl.

From PyPI

Use this for the latest published release.

Quick try (no installation):

uvx --python 3.13 langrepl@latest
uvx --python 3.13 langrepl@latest -w /path  # specify working dir

Install globally:

uv tool install --python 3.13 langrepl

Upgrading: Run uv tool upgrade --python 3.13 langrepl if installed globally, or use uvx --python 3.13 langrepl@latest for ephemeral runs.

From Source

git clone https://github.com/midodimori/langrepl.git
cd langrepl
make install        # install deps + pre-commit hooks
uv run langrepl     # run locally without global install

To install globally from source:

uv tool install --python 3.13 --editable .

Then run from any directory (same as above).

Environment Variables

Configure langrepl using environment variables via .env file or shell exports.

Using .env file (recommended):

# Create .env in your working directory
LLM__OPENAI_API_KEY=your_openai_api_key_here
LANGCHAIN_TRACING_V2=true

Using shell exports:

export LLM__OPENAI_API_KEY=your_openai_api_key_here
export LANGCHAIN_TRACING_V2=true

LLM Provider API Keys

# OpenAI
LLM__OPENAI_API_KEY=your_openai_api_key_here

# Anthropic
LLM__ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Google
LLM__GOOGLE_API_KEY=your_google_api_key_here

# DeepSeek
LLM__DEEPSEEK_API_KEY=your_deepseek_api_key_here

# Zhipu AI
LLM__ZHIPUAI_API_KEY=your_zhipuai_api_key_here

# Moonshot AI (Kimi)
LLM__MOONSHOT_API_KEY=your_moonshot_api_key_here
# Optional: for China region
# LLM__MOONSHOT_BASE_URL=https://api.moonshot.cn/v1

# AWS Bedrock (optional, falls back to AWS CLI credentials)
LLM__AWS_ACCESS_KEY_ID=your_aws_access_key_id
LLM__AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
LLM__AWS_SESSION_TOKEN=your_aws_session_token  # Optional

# Local model base URLs
LLM__OLLAMA_BASE_URL=http://localhost:11434      # Default
LLM__LMSTUDIO_BASE_URL=http://localhost:1234/v1  # Default

Tracing

LangSmith (recommended for debugging):

LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langsmith_api_key
LANGCHAIN_PROJECT=your_project_name              # Optional
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com  # Default

Proxy Settings

LLM__HTTP_PROXY=http://proxy.example.com:8080
LLM__HTTPS_PROXY=https://proxy.example.com:8443

Tool Settings

TOOL_SETTINGS__MAX_COLUMNS=1500      # Grep max columns (default: 1500)
TOOL_SETTINGS__CONTEXT_LINES=2       # Grep context lines (default: 2)
TOOL_SETTINGS__SEARCH_LIMIT=25       # Grep search limit (default: 25)

CLI Settings

CLI__THEME=tokyo-night               # UI theme (default: none (auto-detect), possible values: tokyo-day, tokyo-night)
CLI__PROMPT_STYLE="❯ "               # Prompt style (default: "❯ ")
CLI__ENABLE_WORD_WRAP=true           # Word wrap (default: true)
CLI__EDITOR=nano                     # Editor for /memory (default: nano)
CLI__MAX_AUTOCOMPLETE_SUGGESTIONS=10 # Autocomplete limit (default: 10)

Server Settings

Server configuration is in .langrepl/config.server.yml (not .env). See AG-UI Server Mode.

Other Settings

LOG_LEVEL=INFO                       # Log level (default: INFO)
SUPPRESS_GRPC_WARNINGS=true          # Suppress gRPC warnings (default: true)

CLI Flags

langrepl [OPTIONS] [MESSAGE]

Positional Arguments

Options

Examples

# Interactive mode with default settings
langrepl

# One-shot mode
langrepl "What is the capital of France?"

# Specify working directory
langrepl -w /path/to/project

# Use specific agent
langrepl -a claude-style-coder

# Override agent's model
langrepl -a general -m gpt-4o

# Resume last conversation
langrepl -r

# Resume with new message
langrepl -r "Continue from where we left off"

# Set approval mode
langrepl -am aggressive

# Server mode (protocol from config.server.yml)
langrepl -s

# Server mode with single agent
langrepl -s -a general

# Verbose logging
langrepl -v

# Combine flags
langrepl -w /my/project -a code-reviewer -am active -v

Quick Start

Langrepl ships with multiple prebuilt agents:

• general (default) - General-purpose agent for research, writing, analysis, and planning
• claude-style-coder - Software development agent mimicking Claude Code's behavior
• code-reviewer - Code review agent focusing on quality and best practices

Interactive Chat Mode

langrepl              # Start interactive session (general agent by default)
langrepl -a general   # Use specific agent
langrepl -r           # Resume last conversation
langrepl -am ACTIVE   # Set approval mode (SEMI_ACTIVE, ACTIVE, AGGRESSIVE)
langrepl -w /path     # Set working directory
lg                    # Quick alias

One-Shot Mode

langrepl "your message here"                    # Send message and exit
langrepl "what is 2+2?" -am aggressive          # With approval mode
langrepl -a general "search for latest news"    # Use specific agent
langrepl -r "continue from where we left off"   # Resume conversation

LangGraph Server Mode

langrepl -s -a general                # Start LangGraph server
langrepl -s -a general -am ACTIVE     # With approval mode

# Server: http://localhost:2024
# Studio: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
# API Docs: http://localhost:2024/docs

Server features:

• Auto-generates langgraph.json configuration
• Creates/updates assistants via LangGraph API
• Enables visual debugging with LangGraph Studio
• Supports all agent configs and MCP servers

AG-UI Server Mode

Configure in .langrepl/config.server.yml:

version: 1.0.0
protocol: ag                          # ag (API only), agui (API + UI), langsmith
backend_url: http://0.0.0.0:8000
frontend_url: http://localhost:3000   # only used with agui

langrepl -s                              # Serve all agents (protocol from config)
langrepl -s -a general                   # Serve only this agent
langrepl -s -a general -m gpt-4o        # Single agent with model override

# Endpoints (multi-agent):
# GET  /agents                        → list available agents
# POST /agent/{name}                  → AG-UI SSE stream per agent
# GET  /agent/{name}/health           → per-agent health check
# GET  /threads                       → list saved threads
# GET  /threads/{id}/messages         → thread message history
# GET  /threads/{id}/state            → full checkpoint state

AG-UI server features:

• AG-UI protocol over Server-Sent Events (SSE)
• Multi-agent serving: all agents from agents/*.yml at /agent/{name}
• Dynamic discovery via GET /agents
• In-process FastAPI + uvicorn (no subprocess)
• Thread persistence via configured checkpointer
• Interrupt-based tool approval (works with semi-active mode)
• Compatible with CopilotKit and any AG-UI client

Chat UI (set protocol: agui in config — auto-launches CopilotKit UI):

langrepl -s   # Starts AG-UI server + CopilotKit UI at localhost:3000

Or manually:

# Terminal 1: start AG-UI backend (protocol: ag)
langrepl -s

# Terminal 2: start CopilotKit frontend
cd ui && pnpm install && pnpm dev

Interactive Commands

Conversation Management

Configuration

Utilities

/todo       # Show max 10 items
/todo 20    # Show max 20 items

Usage

Configs are auto-generated in .langrepl/ on first run.

Agents

.langrepl/agents/*.yml:

# agents/my-agent.yml (filename must match agent name)
version: 2.2.0
name: my-agent
prompt: prompts/my_agent.md  # Single file or array of files
llm: haiku-4.5               # References llms/*.yml
checkpointer: sqlite         # References checkpointers/*.yml
recursion_limit: 40
default: true
tools:
  patterns:
    - impl:file_system:read_file
    - mcp:context7:resolve-library-id
  use_catalog: false         # Use tool catalog to reduce token usage
  output_max_tokens: 10000   # Max tokens per tool output
skills:
  patterns:
    - general:skill-creator  # References skills/<category>/<name>
subagents:
  - general-purpose          # References subagents/*.yml
compression:
  auto_compress_enabled: true
  auto_compress_threshold: 0.8
  llm: haiku-4.5
  prompt:
    - prompts/shared/general_compression.md
    - prompts/suffixes/environments.md
  messages_to_keep: 0  # Keep N recent messages verbatim during compression
sandboxes:                    # See Sandboxes section
  enabled: true
  profiles:
    - sandbox: rw-online-macos
      patterns: [impl:*:*, "!impl:terminal:*"]
    - sandbox: null            # Bypass for excluded tools
      patterns: [impl:terminal:*, mcp:*:*]

agents:
  - version: 2.2.0
    name: my-agent
    prompt: prompts/my_agent.md
    llm: haiku-4.5
    checkpointer: sqlite
    recursion_limit: 40
    default: true
    tools:
      patterns:
        - impl:file_system:read_file
        - mcp:context7:resolve-library-id
      use_catalog: false         # Use tool catalog to reduce token usage
      output_max_tokens: 10000   # Max tokens per tool output
    skills:
      patterns:
        - general:skill-creator  # References skills/<category>/<name>
    subagents:
      - general-purpose
    compression:
      auto_compress_enabled: true
      auto_compress_threshold: 0.8
      llm: haiku-4.5
      prompt:
        - prompts/shared/general_compression.md
        - prompts/suffixes/environments.md
      messages_to_keep: 0  # Keep N recent messages verbatim during compression

Tool naming: <category>:<module>:<function> with wildcard (*, ?, [seq]) and negative (!) pattern support

• impl:*:* - All built-in tools
• impl:file_system:read_* - All read_* tools in file_system
• !impl:file_system:write_* - Exclude write_* tools
• mcp:server:* - All tools from MCP server

Tool catalog: When use_catalog: true, impl/mcp tools are wrapped in a unified catalog interface to reduce token usage. The agent receives catalog tools instead of individual tool definitions.

Available Tools

Custom Prompts

Place prompts in .langrepl/prompts/:

# prompts/my_agent.md
You are a helpful assistant...

{user_memory}

Placeholders:

• {user_memory} - Auto-appended if missing
• {conversation} - Auto-wrapped if missing (compression prompts only)

LLMs

.langrepl/llms/*.yml:

# llms/anthropic.yml (organize by provider, filename is flexible)
- version: 1.0.0
  model: claude-haiku-4-5
  alias: haiku-4.5
  provider: anthropic
  max_tokens: 10000
  temperature: 0.1
  context_window: 200000
  input_cost_per_mtok: 1.00
  output_cost_per_mtok: 5.00

llms:
  - version: 1.0.0
    model: claude-haiku-4-5
    alias: haiku-4.5
    provider: anthropic
    max_tokens: 10000
    temperature: 0.1
    context_window: 200000
    input_cost_per_mtok: 1.00
    output_cost_per_mtok: 5.00

Checkpointers

.langrepl/checkpointers/*.yml:

# checkpointers/sqlite.yml (filename must match checkpointer type)
version: 1.0.0
type: sqlite
max_connections: 10

# checkpointers/memory.yml (filename must match checkpointer type)
version: 1.0.0
type: memory
max_connections: 1

checkpointers:
  - version: 1.0.0
    type: sqlite
    max_connections: 10
  - version: 1.0.0
    type: memory
    max_connections: 1

Checkpointer types:

• sqlite - Persistent SQLite-backed storage (default, stored in .langrepl/.db/checkpoints.db)
• memory - In-memory storage (ephemeral, lost on exit)

Sub-Agents

Sub-agents use the same config structure as main agents.

.langrepl/subagents/*.yml:

# subagents/code-reviewer.yml (filename must match subagent name)
version: 2.0.0
name: code-reviewer
prompt: prompts/code-reviewer.md
llm: haiku-4.5
tools:
  patterns: [impl:file_system:read_file]
  use_catalog: false
  output_max_tokens: 10000

agents:
  - version: 2.0.0
    name: code-reviewer
    prompt: prompts/code-reviewer.md
    llm: haiku-4.5
    tools:
      patterns: [impl:file_system:read_file]
      use_catalog: false
      output_max_tokens: 10000

Add custom: Create prompt, add config file, reference in parent agent's subagents list.

Custom Tools

1. Implement in src/langrepl/tools/impl/my_tool.py:

   from langchain.tools import tool
   
   @tool()
   def my_tool(query: str) -> str:
       """Tool description."""
       return result
   

2. Register in src/langrepl/tools/factory.py:

   MY_TOOLS = [my_tool]
   self.impl_tools.extend(MY_TOOLS)
   

3. Reference: impl:my_tool:my_tool

Skills

Skills are modular knowledge packages that extend agent capabilities. See anthropics/skills for details.

Directory structure (.langrepl/skills/):

skills/
├── general/
│   └── skill-creator/
│       ├── SKILL.md            # Required: metadata and instructions
│       ├── scripts/            # Optional: executable code
│       ├── references/         # Optional: documentation
│       └── assets/             # Optional: templates, images, etc.
└── custom-category/
    └── my-skill/
        └── SKILL.md

Skill naming: <category>:<name> with wildcard (*) and negative (!) pattern support

• general:skill-creator - Specific skill
• general:* - All skills in category
• !general:dangerous-skill - Exclude specific skill
• *:* - All skills

Built-in: skill-creator - Guide for creating custom skills

Server (config.server.yml)

version: 1.0.0
protocol: ag                          # ag | agui | langsmith
backend_url: http://0.0.0.0:8000
frontend_url: http://localhost:3000   # only used with agui

• protocol: ag starts AG-UI server only, agui starts AG-UI server + CopilotKit UI, langsmith starts LangGraph Platform server
• backend_url: server bind address for ag/agui, LangGraph Platform URL for langsmith
• Auto-generated for new workspaces. For existing workspaces, create manually or use defaults
• See AG-UI Server Mode for usage

MCP Servers (config.mcp.json)

{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-mcp-package"],
      "transport": "stdio",
      "enabled": true,
      "stateful": false,
      "include": ["tool1"],
      "exclude": [],
      "repair_command": ["rm", "-rf", ".some_cache"],
      "repair_timeout": 30,
      "invoke_timeout": 60.0
    },
    "remote-server": {
      "url": "http://localhost:8080/mcp",
      "transport": "http",
      "timeout": 30,
      "sse_read_timeout": 300,
      "invoke_timeout": 60.0
    }
  }
}

• transport: stdio (local command), http (HTTP/streamable), sse (Server-Sent Events), websocket. Aliases streamable_http and streamable-http map to http.
• timeout, sse_read_timeout: Connection and SSE read timeouts in seconds (for HTTP-based transports)
• stateful: Keep connection alive between tool calls (default: false). Use for servers that need persistent state.
• repair_command: Command array to run if server fails (default: none). Auto-retries after repair.
• repair_timeout: Repair command timeout in seconds (default: 30 when repair_command is set)
• invoke_timeout: Tool invocation timeout in seconds (default: none)
• Suppress stderr: "command": "sh", "args": ["-c", "npx pkg 2>/dev/null"]
• Reference: mcp:my-server:tool1
• Examples: useful-mcp-servers.json

Tool Approval (config.approval.json)

{
  "always_allow": [
    { "name": "read_file", "args": null }
  ],
  "always_deny": [
    { "name": "run_command", "args": { "command": "rm -rf /.*" } }
  ],
  "always_ask": [
    { "name": "run_command", "args": { "command": "rm\\s+-rf.*" } },
    { "name": "run_command", "args": { "command": "git\\s+push.*" } },
    { "name": "run_command", "args": { "command": "git\\s+reset\\s+--hard.*" } },
    { "name": "run_command", "args": { "command": "sudo\\s+.*" } }
  ]
}

Three rule lists:

• always_deny - Permanently blocked (highest priority)
• always_ask - Always prompt, even in ACTIVE mode (for critical commands)
• always_allow - Auto-approved

Modes and behavior:

Default always_ask rules protect against destructive commands like rm -rf, git push, git reset --hard, and sudo.

Sandboxes (Beta)

Sandboxes provide secure, isolated execution environments for tools. They restrict filesystem access, network connectivity, and system calls to prevent potentially dangerous operations.

Prerequisites:

• macOS: Built-in sandbox-exec (no installation needed)
• Linux: bubblewrap package required (see Prerequisites)

.langrepl/sandboxes/*.yml:

# sandboxes/rw-online-macos.yml (filename must match sandbox name)
version: "1.0.0"
name: rw-online-macos
type: seatbelt      # macOS: seatbelt, Linux: bubblewrap
os: macos           # macos or linux

filesystem:
  read:
    - "."           # Working directory
    - "/usr"        # System binaries
    - "~/.local"    # User tools (uvx, pipx)
  write:
    - "."
    - "/private/tmp"
  hidden:           # Blocked paths (glob patterns)
    - ".env"
    - "~/.ssh"
    - "*.pem"

network:
  remote:
    - "*"           # "*" = allow all, [] = deny all
  local: []         # Unix sockets

Default profiles (auto-copied per platform on first run):

Notes:

• Package managers: uvx, npx, pip may need network to check/download from registries. Default profiles include ~/.cache/uv, ~/.npm, ~/.local for caching. Offline sandboxes auto-inject NPM_CONFIG_OFFLINE=true and UV_OFFLINE=1 for MCP servers.
• Docker/containers: Docker CLI requires socket access. Add to network.local: Docker Desktop (/var/run/docker.sock), OrbStack (~/.orbstack/run/docker.sock), Rancher Desktop (~/.rd/docker.sock), Colima (~/.colima/default/docker.sock).
• MCP servers: Sandboxed at startup (command wrapped). Match with mcp:server-name:* (tool part must be *). HTTP servers require explicit bypass (sandbox: null).
• Sandbox patterns: Support negative patterns. Use !mcp:server:* to exclude from a wildcard match. Tools/servers must match exactly one profile or they're blocked.
• Working directory ("."): When included, mounted and used as cwd. When excluded: Linux = not mounted, cwd is / inside tmpfs; macOS = can list files but cannot read contents.
• Symlinks: Symlinks resolving outside allowed boundaries are blocked. Warnings logged at startup. Add targets to filesystem.read if needed.

Limitations:

• Network (remote): Binary - ["*"] allows all TCP/UDP, [] blocks all. ["*"] reserved for future domain filtering.
• Network (local): macOS = allowlist-based. Linux = binary (empty blocks all, any entry allows all); per-socket filtering reserved for future.
• macOS (Seatbelt): Deny-by-default policy. Mach services allowed for DNS, TLS, keychain.
• Linux (Bubblewrap): Namespace isolation (user, pid, ipc, uts, network). pyseccomp optional for syscall blocking.
• Other: Sandbox worker only executes built-in tools (from langrepl.tools.* module). 60s timeout. 10MB stdout / 1MB stderr limits. Hidden patterns use gitignore-style glob.

Development

For local development without global install:

git clone https://github.com/midodimori/langrepl.git
cd langrepl
make install

Run from within repository:

uv run langrepl              # Start interactive session
uv run langrepl -w /path     # Specify working directory
uv run langrepl -s             # Start server (protocol from config.server.yml)
uv run langrepl -s -a general  # Start server with single agent

Development commands:

make install      # Install dependencies + pre-commit hooks
make lint-fix     # Format and lint code
make test         # Run tests
make pre-commit   # Run pre-commit on all files
make clean        # Remove cache/build artifacts

License

This project is licensed under the MIT License - see the LICENSE file for details.