Langrepl

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

demo.mov

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
Multi-Provider LLM Support - OpenAI, Anthropic, Google, AWS Bedrock, Ollama, DeepSeek, ZhipuAI, 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 the MCP protocol

Prerequisites

Python 3.13+ - Required for the project
uv - Fast Python package installer (install instructions)
ripgrep (rg) - Required for fast code search (grep_search tool) and directory structure visualization (get_directory_structure tool):
- macOS: brew install ripgrep
- Ubuntu/Debian: sudo apt install ripgrep
- Arch Linux: sudo pacman -S ripgrep
- Windows: choco install ripgrep or download from releases
fd - Required for fast file/directory completion with @ (fallback when not in a Git repository):
- macOS: brew install fd
- Ubuntu/Debian: sudo apt install fd-find
- Arch Linux: sudo pacman -S fd
- Windows: choco install fd or download from releases
Node.js & npm (optional) - Required only if using MCP servers that run via npx

Installation

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

From PyPI

Quick try (no installation):

uvx langrepl
uvx langrepl -w /path  # specify working dir

Install globally:

uv tool install langrepl
# or with pipx:
pipx install langrepl

Then run from any directory:

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

From GitHub

Quick try (no installation):

uvx --from git+https://github.com/midodimori/langrepl langrepl
uvx --from git+https://github.com/midodimori/langrepl langrepl -w /path  # specify working dir

Install globally:

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

Then run from any directory:

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

From Source

Clone and install:

git clone https://github.com/midodimori/langrepl.git
cd langrepl
make install
uv tool install --editable .

Then run from any directory (same as above).

Configure API Keys

Set API keys via .env:

LLM__OPENAI_API_KEY=your_openai_api_key_here
LLM__ANTHROPIC_API_KEY=your_anthropic_api_key_here
LLM__GOOGLE_API_KEY=your_google_api_key_here
LLM__DEEPSEEK_API_KEY=your_deepseek_api_key_here
LLM__ZHIPUAI_API_KEY=your_zhipuai_api_key_here

Tracing

LangSmith

Add to .env:

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

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

Interactive Commands

Conversation Management

/resume - Switch between conversation threads

Shows list of all saved threads with timestamps. Select one to continue that conversation.

/replay - Branch from previous message

Shows all previous human messages in current thread. Select one to branch from that point while preserving the original conversation.

/compress - Compress conversation history

Compresses messages using LLM summarization to reduce token usage. Creates new thread with compressed history (e.g., 150 messages/45K tokens → 3 messages/8K tokens).

/clear - Start new conversation

Clear screen and start a new conversation thread while keeping previous thread saved.

Configuration

/agents - Switch agent

Shows all configured agents with interactive selector. Switch between specialized agents (e.g., coder, researcher, analyst).

/model - Switch LLM model

Shows all configured models with interactive selector. Switch between models for cost/quality tradeoffs.

/tools - View available tools

Lists all tools available to the current agent from impl/, internal/, and MCP servers.

/mcp - Manage MCP servers

View and toggle enabled/disabled MCP servers interactively.

/memory - Edit user memory

Opens .langrepl/memory.md for custom instructions and preferences. Content is automatically injected into agent prompts.

/skills - View available skills

Lists all skills available to the current agent with interactive selector. Skills are specialized knowledge packages that extend agent capabilities.

Utilities

/graph [--browser] - Visualize agent graph

Renders in terminal (ASCII) or opens in browser with --browser flag.

/help - Show help

/exit - Exit application

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

Single-file format: .langrepl/config.agents.yml

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 support (*, ?, [seq])

impl:*:* - All built-in tools
impl:file_system:read_* - All read_* tools in file_system
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.

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

Single-file format: .langrepl/config.llms.yml

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

Single-file format: .langrepl/config.checkpointers.yml

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

Single-file format: .langrepl/config.subagents.yml

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

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

from langchain.tools import tool

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

Register in src/tools/factory.py:

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

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 support

general:skill-creator - Specific skill
general:* - All skills in category
*:* - All skills

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

MCP Servers (`config.mcp.json`)

{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-mcp-package"],
      "transport": "stdio",
      "enabled": true,
      "include": ["tool1"],
      "exclude": [],
      "repair_command": "rm -rf .some_cache"
    }
  }
}

repair_command: Runs if server fails, then run this command before retrying
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
    },
    {
      "name": "run_command",
      "args": "pwd"
    }
  ],
  "always_deny": [
    {
      "name": "run_command",
      "args": "rm -rf /.*"
    }
  ]
}

Modes: SEMI_ACTIVE (ask unless whitelisted), ACTIVE (auto-approve except denied), AGGRESSIVE (bypass all)

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 -a general  # Start LangGraph server

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.

Name		Name	Last commit message	Last commit date
Latest commit History 156 Commits
.github/workflows		.github/workflows
examples		examples
resources		resources
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Langrepl

Table of Contents

Features

Prerequisites

Installation

From PyPI

From GitHub

From Source

Configure API Keys

Tracing

LangSmith

Quick Start

Interactive Chat Mode

One-Shot Mode

LangGraph Server Mode

Interactive Commands

Conversation Management

Configuration

Utilities

Usage

Agents

Custom Prompts

LLMs

Checkpointers

Sub-Agents

Custom Tools

Skills

MCP Servers (config.mcp.json)

Tool Approval (config.approval.json)

Development

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

MCP Servers (`config.mcp.json`)

Tool Approval (`config.approval.json`)

Packages