DOCSEARCHbyAlgolia
Submit Docs

Langrepl

repository·main·Indexed 41 days ago

https://github.com/midodimori/langrepl

An interactive terminal CLI and server for building and running LLM agents, built with LangChain, LangGraph, Prompt Toolkit, and Rich. Version 1.12.1 supports deep agent architectures including planning tools, sub-agent delegation, and persistent conversations. It features interactive chat and one-shot modes, LangGraph server mode for visual debugging, and AG-UI server mode for SSE-based agent serving. Compatible with macOS and Linux.

Tokens
36.7K
Snippets
109
Records
154
Agent score
50%

What's inside Langrepl

  1. Understand the Langrepl AG-UI Demo structure

    main

    The demo project is organized into the following key areas:

    Application Logic (src/app/)

    • api/copilotkit/route.ts: Acts as a proxy between the CopilotKit runtime and the LangGraphHttpAgent.
    • layout.tsx: Contains the CopilotKit provider and dark theme configuration.
    • page.tsx: Implements a two-panel layout consisting of a chat interface and a state inspector.
    • globals.css: Contains Tailwind CSS and CopilotChat overrides.

    UI Components (src/components/)

    • approval-handler.tsx: Handles interrupt dialogs for tool approval.
    • state-inspector.tsx: A JSON viewer for inspecting the agent's state.
    • step-progress.tsx: A visual indicator for processing steps.

  2. Use Sandboxes for Secure Tool Execution

    main

    Sandboxes provide isolated environments for tools to prevent dangerous operations. Configurations are in .langrepl/sandboxes/*.yml.

    Supported Types:

    • macOS: Uses seatbelt (built-in).
    • Linux: Uses bubblewrap (requires bubblewrap package installed).

    Configuration Options:

    • filesystem.read / filesystem.write: Lists of allowed paths (supports glob patterns).
    • filesystem.hidden: Blocked paths (e.g., .env, ~/.ssh).
    • network.remote: ["*"] allows all, [] denies all.
    • network.local: Allowlist of Unix sockets.

    Default Profiles:

    • rw-online-{os}: Read/Write access + Network.
    • rw-offline-{os}: Read/Write access, No Network.
    • ro-online-{os}: Read-only access + Network.
    • ro-offline-{os}: Read-only access, No Network.

    Note: To bypass sandboxing for specific tools, use sandbox: null in the agent's tool configuration.

    # sandboxes/rw-online-macos.yml
version: "1.0.0"
name: rw-online-macos
type: seatbelt
os: macos

filesystem:
  read:
    - "."
    - "/usr"
    - "~/.local"
  write:
    - "."
    - "/private/tmp"
  hidden:
    - ".env"
    - "~/.ssh"

etwork:
  remote:
    - "*"
  local: []

  3. How the Codebase Explorer Agent works

    main

    The Codebase Explorer Agent is a specialized worker subagent designed to perform deep codebase exploration. Its primary purpose is to assist a main agent by identifying code structures, architectural patterns, component interactions, and specific implementations.

    Exploration Lifecycle

    1. Analyze: Identify the target code or pattern.
    2. Search: Use grep_search with strategic regex patterns.
    3. Examine: Use read_file to inspect implementation details.
    4. Reflect: Use the think tool after searches to analyze results and plan subsequent steps.
    5. Synthesize: Combine findings into a final, actionable report.

    Search Best Practices

    • Broad to Narrow: Start with broad searches to map the landscape before drilling down.
    • Semantic Matching: Use conceptual terms rather than just literal string matches.
    • Regex Optimization: Use the OR operator for related terms (e.g., (term1|term2)) and include context in patterns (e.g., function_name\( instead of just function_name).
    • Dual Search: Search both filenames and file contents.

  4. Use Tool Naming Patterns and Wildcards

    main

    Tools are referenced using the pattern <category>:<module>:<function>. Langrepl supports wildcards (*, ?, [seq]) and negative patterns (!) for tool selection:

    • impl:*:*: All built-in tools.
    • impl:file_system:read_*: All tools starting with read_ in the file_system module.
    • !impl:file_system:write_*: Excludes all write_* tools in the file_system module.
    • mcp:server:*: All tools provided by a specific MCP server.

    Tool Catalog: If use_catalog: true is set in the agent config, tools are wrapped in a unified interface. The agent uses fetch_tools, get_tool, and run_tool instead of receiving individual tool definitions, which helps reduce token usage.

  5. Configure a General-Purpose Subagent prompt

    main

    The general-purpose.md prompt defines the persona and operational logic for a specialized worker subagent in Langrepl. This agent is designed to assist a main agent by executing complex, multi-step tasks autonomously.

    Core Responsibilities

    • Researching: Answering complex questions via multiple searches and analysis.
    • Code Analysis: Finding and understanding patterns across a codebase.
    • Information Gathering: Synthesizing data from code, web, and documentation.
    • Workflow Execution: Planning and executing multi-step workflows.

    Task Execution Workflow

    Subagents follow a five-step process:

    1. Understand: Break the request into objectives.
    2. Plan: Identify required information and sources.
    3. Execute: Systematically use tools like grep_search, read_file, fetch_web_content, and think.
    4. Synthesize: Combine findings into a coherent answer.
    5. Recommend: Provide actionable guidance.

    Output Requirements

    • Completeness: The final message sent by the subagent is the only thing returned to the main agent; it must be a complete, standalone response.
    • Structure: Answers must be well-organized and include specific code snippets.
    • Citations: Always cite sources using file paths with line numbers or URLs.
    • Actionability: Focus on recommendations the user can implement, including trade-offs and alternatives.

  6. Run LangGraph Server Mode

    main

    Start a LangGraph server to enable visual debugging with LangGraph Studio and automated assistant management. The server auto-generates langgraph.json and supports all agent configurations and MCP servers.

    • Server URL: http://localhost:2024
    • LangGraph Studio: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
    • API Docs: http://localhost:2024/docs
    langrepl -s -a general                # Start LangGraph server
langrepl -s -a general -am ACTIVE     # Start with specific approval mode

  7. Apply additional summarization instructions to code_compression

    main

    When using the code_compression prompt, you can provide additional context-specific instructions to refine the summary focus. These instructions should be passed alongside the main prompt to modify how the assistant prioritizes information.

    Examples of instruction patterns:

    • Focusing on specific languages/errors: "When summarizing the conversation focus on typescript code changes and also remember the mistakes you made and how you fixed them."
    • Focusing on testing/verbatim content: "When you are using compact - please focus on test output and code changes. Include file reads verbatim."

  8. Use Langrepl in One-Shot Mode

    main

    Send a single message to an agent and exit immediately without entering an interactive session. This is useful for scripting or quick queries.

    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

  9. Prerequisites for Langrepl

    main

    Langrepl is only supported on macOS and Linux. Windows is not supported.

    Required Software

    • Python 3.13+ (Check with python3 --version)
    • uv (Python package manager)
    • ripgrep (rg) (Required for code search)
    • fd (Required for file/directory completion)
    • tree (Required for file system visualization)

    Optional Software

    • bubblewrap (Linux only): Required for the Sandbox feature.
    • Node.js & npm: Required for MCP servers running via npx and for the AG-UI chat UI.
    • pnpm: Required for the AG-UI chat UI (ui/ directory).

  10. Run AG-UI Server Mode

    main

    Serve agents using the AG-UI protocol over Server-Sent Events (SSE). This mode is compatible with CopilotKit and any AG-UI client. You can configure the server via .langrepl/config.server.yml.

    Configuration Keys (.langrepl/config.server.yml):

    • version: Protocol version.
    • protocol: ag (API only), agui (API + UI), or langsmith.
    • backend_url: The server address.
    • frontend_url: The UI address (used with agui).

    API Endpoints:

    • 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.
    # .langrepl/config.server.yml
version: 1.0.0
protocol: ag
backend_url: http://0.0.0.0:8000
frontend_url: http://localhost:3000
    langrepl -s                              # Serve all agents (uses config protocol)
langrepl -s -a general                   # Serve only the 'general' agent
langrepl -s -a general -m gpt-4o          # Serve 'general' agent with model override

  11. Install langrepl for local development

    main

    To set up a local development environment without a global installation, clone the repository and use make install to set up dependencies and pre-commit hooks.

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

  12. Implement Custom Tools

    main

    To add a new tool to Langrepl, follow these three steps:

    1. Implement the tool in src/langrepl/tools/impl/<my_tool>.py using the @tool decorator from langchain:

      from langchain.tools import tool

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

    2. Register the tool in src/langrepl/tools/factory.py by adding it to the MY_TOOLS list and extending self.impl_tools.

    3. Reference it in your agent config using the pattern impl:my_tool:my_tool.

    # 1. Implementation
from langchain.tools import tool

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