REPL Module

REPL Module#

The REPL (Read-Eval-Print Loop) module provides a feature-rich interactive command-line interface for agents and teams.

Overview#

The REPL module provides:

Interactive chat with agents and teams
Syntax highlighting for code and markdown
Full-screen file viewer with navigation
Interactive approval workflows
Command history and auto-completion
Session management and persistence

Starting the REPL#

Command Line#

The easiest way to start the REPL:

pantheon cli

With options:

# Specify a team template
pantheon cli --team myteam

# Specify memory directory
pantheon cli --memory-dir ./chats

# Resume a specific chat
pantheon cli --chat-id abc123

Programmatic Usage#

import asyncio
from pantheon.repl import Repl
from pantheon.agent import Agent

async def main():
    agent = Agent(
        name="assistant",
        instructions="You are helpful."
    )

    repl = Repl(agent=agent)
    await repl.run()

asyncio.run(main())

With Teams#

from pantheon.repl import Repl
from pantheon.team import PantheonTeam
from pantheon.agent import Agent

async def main():
    agents = [
        Agent(name="researcher", instructions="..."),
        Agent(name="writer", instructions="...")
    ]

    team = PantheonTeam(agents)
    repl = Repl(agent=team)
    await repl.run()

With ChatRoom#

from pantheon.repl import Repl
from pantheon.chatroom import ChatRoom

async def main():
    chatroom = ChatRoom()
    repl = Repl(chatroom=chatroom)
    await repl.run()

REPL Commands#

Built-in Commands#

The REPL provides several built-in slash commands:

/help - Show available commands
/view <filepath> - Open full-screen file viewer
/clear - Clear conversation context
/compress - Compress conversation history to save tokens
/exit or /quit - Exit the REPL

File Viewer#

The /view command opens a full-screen file viewer with:

Syntax highlighting via Pygments
Keyboard navigation:
- j/k or arrow keys: Scroll up/down
- Space or Ctrl-F: Page down
- Ctrl-B: Page up
- g: Go to top
- G: Go to bottom
- q or Esc: Exit viewer

Example:

> /view src/main.py

Interactive Approval#

When agents request user approval (via notify_user with interrupt=True), an interactive dialog appears with:

Markdown-rendered notification message
File preview with multi-file switching (keys 1-9, Tab)
Action buttons:
- a: Approve
- c: Continue planning
- Esc: Reject/Cancel

Multi-line Input#

For multi-line messages, use triple backticks:

> ```
This is a
multi-line
message
```

REPL Class#

Bases: ReplUI

REPL for agent or team interaction, based on ChatRoom.

Supports multiple initialization modes: - agent: Pass an Agent or Team directly (legacy mode, creates embedded ChatRoom) - chatroom: Pass an existing ChatRoom instance - endpoint: Pass an Endpoint instance (creates ChatRoom with it) - None: Auto-create ChatRoom with embedded Endpoint

Parameters:

agent – An Agent or Team instance (legacy mode).
chatroom – An existing ChatRoom instance.
endpoint – An Endpoint instance to create ChatRoom with.
memory_dir – Directory for chat persistence.
chat_id – Specific chat ID to use (creates new if None).

__init__(agent: Agent | Team | None = None, chatroom: ChatRoom | None = None, endpoint: Endpoint | None = None, memory_dir: str | None = None, chat_id: str | None = None)[source][source]#

register_handler(handler: CommandHandler | str | Path)[source][source]#: Register a handler for processing commands.

handle_interrupt() → bool[source][source]#

Handle Ctrl+C interrupt with double-press logic.

Returns:: True if should exit (double press), False otherwise.

ask_user_input() → str[source][source]#: Get user input with multi-line support and readline history.

async run(message: str | dict | None = None, disable_logging: bool = True, log_to_file: bool = True, log_level: str = 'CRITICAL')[source][source]#

Main REPL loop.

Parameters:

message – Optional initial message to process
disable_logging – If True, suppress console logging (only show ERROR)
log_to_file – If True, save all logs to .pantheon/logs/ (even when console logging is suppressed)

Initialization Modes#

The Repl class supports multiple initialization modes:

Agent Mode: Pass an Agent or Team directly
```
repl = Repl(agent=my_agent)
```
ChatRoom Mode: Pass an existing ChatRoom
```
repl = Repl(chatroom=my_chatroom)
```
Endpoint Mode: Pass an Endpoint instance
```
repl = Repl(endpoint=my_endpoint)
```

Auto Mode: Create everything automatically

repl = Repl()  # Auto-creates ChatRoom and Endpoint

Configuration#

repl = Repl(
    agent=my_agent,
    memory_dir="./chat_history",  # Directory for persistence
    chat_id="session-123",        # Specific chat session ID
)

UI Components#

ReplUI#

Base class providing UI rendering capabilities:

Console output with Rich
Progress indicators
Token statistics display
Task rendering

TaskUIRenderer#

Renders task progress and status:

Tool execution progress
Agent thinking indicators
Cost and token tracking

NotifyUIRenderer#

Renders notification panels and approval dialogs.

Viewers Module#

FileViewer#

Full-screen file viewer using prompt_toolkit:

from pantheon.repl.viewers import FileViewer

async def view_file():
    viewer = FileViewer()
    await viewer.view("path/to/file.py")

Features:

Syntax highlighting for 100+ languages
Line numbers
Smooth scrolling
Multiple encoding support

NotifyDialog#

Interactive dialog for agent approval workflows:

from pantheon.repl.viewers import NotifyDialog

dialog = NotifyDialog(
    message="Agent wants to modify files",
    files=["file1.py", "file2.py"]
)
result = await dialog.show()

Command Handlers#

Base Handler#

from pantheon.repl.handlers.base import CommandHandler

class MyHandler(CommandHandler):
    def __init__(self, console, repl):
        super().__init__(console, repl)

    def can_handle(self, command: str) -> bool:
        return command.startswith("/mycommand")

    async def handle(self, command: str) -> bool:
        # Handle the command
        return True  # Consumed the command

Registering Custom Handlers#

class CustomRepl(Repl):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.handlers.append(MyCustomHandler(self.console, self))

Best Practices#

Use Templates: Define agent/team configurations in .pantheon/ for reusability
Memory Management: Use /compress periodically for long conversations
File Viewer: Use /view to inspect files before editing
History: Use arrow keys to navigate command history
Interrupts: Use Ctrl+C gracefully to interrupt long operations

Integration Examples#

Development Workflow#

from pantheon.repl import Repl
from pantheon.agent import Agent
from pantheon.toolsets import FileManagerToolSet, ShellToolSet

async def dev_repl():
    agent = Agent(
        name="developer",
        instructions="You are a developer assistant."
    )
    await agent.toolset(FileManagerToolSet("files"))
    await agent.toolset(ShellToolSet("shell"))

    repl = Repl(agent=agent)
    await repl.run()

Data Analysis#

from pantheon.repl import Repl
from pantheon.agent import Agent
from pantheon.toolsets import IntegratedNotebookToolSet

async def analysis_repl():
    agent = Agent(
        name="analyst",
        instructions="You are a data analyst."
    )
    await agent.toolset(IntegratedNotebookToolSet("notebook"))

    repl = Repl(agent=agent)
    await repl.run()