deepagents-cli 0.0.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

deepagents_cli/__init__.py

@@ -0,0 +1,5 @@
+"""DeepAgents CLI - Interactive AI coding assistant."""
+
+from .main import cli_main
+
+__all__ = ["cli_main"]

deepagents_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the CLI as: python -m deepagents.cli"""
+
+from .main import cli_main
+
+if __name__ == "__main__":
+    cli_main()

deepagents_cli/agent.py

@@ -0,0 +1,278 @@
+"""Agent management and creation for the CLI."""
+
+import os
+import shutil
+from pathlib import Path
+
+from deepagents import create_deep_agent
+from deepagents.backends import CompositeBackend
+from deepagents.backends.filesystem import FilesystemBackend
+from deepagents.middleware.agent_memory import AgentMemoryMiddleware
+from deepagents.middleware.resumable_shell import ResumableShellToolMiddleware
+from langchain.agents.middleware import HostExecutionPolicy
+from langgraph.checkpoint.memory import InMemorySaver
+
+from .config import COLORS, config, console, get_default_coding_instructions
+
+
+def list_agents():
+    """List all available agents."""
+    agents_dir = Path.home() / ".deepagents"
+
+    if not agents_dir.exists() or not any(agents_dir.iterdir()):
+        console.print("[yellow]No agents found.[/yellow]")
+        console.print(
+            "[dim]Agents will be created in ~/.deepagents/ when you first use them.[/dim]",
+            style=COLORS["dim"],
+        )
+        return
+
+    console.print("\n[bold]Available Agents:[/bold]\n", style=COLORS["primary"])
+
+    for agent_path in sorted(agents_dir.iterdir()):
+        if agent_path.is_dir():
+            agent_name = agent_path.name
+            agent_md = agent_path / "agent.md"
+
+            if agent_md.exists():
+                console.print(f"  • [bold]{agent_name}[/bold]", style=COLORS["primary"])
+                console.print(f"    {agent_path}", style=COLORS["dim"])
+            else:
+                console.print(
+                    f"  • [bold]{agent_name}[/bold] [dim](incomplete)[/dim]", style=COLORS["tool"]
+                )
+                console.print(f"    {agent_path}", style=COLORS["dim"])
+
+    console.print()
+
+
+def reset_agent(agent_name: str, source_agent: str = None):
+    """Reset an agent to default or copy from another agent."""
+    agents_dir = Path.home() / ".deepagents"
+    agent_dir = agents_dir / agent_name
+
+    if source_agent:
+        source_dir = agents_dir / source_agent
+        source_md = source_dir / "agent.md"
+
+        if not source_md.exists():
+            console.print(
+                f"[bold red]Error:[/bold red] Source agent '{source_agent}' not found or has no agent.md"
+            )
+            return
+
+        source_content = source_md.read_text()
+        action_desc = f"contents of agent '{source_agent}'"
+    else:
+        source_content = get_default_coding_instructions()
+        action_desc = "default"
+
+    if agent_dir.exists():
+        shutil.rmtree(agent_dir)
+        console.print(f"Removed existing agent directory: {agent_dir}", style=COLORS["tool"])
+
+    agent_dir.mkdir(parents=True, exist_ok=True)
+    agent_md = agent_dir / "agent.md"
+    agent_md.write_text(source_content)
+
+    console.print(f"✓ Agent '{agent_name}' reset to {action_desc}", style=COLORS["primary"])
+    console.print(f"Location: {agent_dir}\n", style=COLORS["dim"])
+
+
+def get_system_prompt() -> str:
+    """Get the base system prompt for the agent.
+
+    Returns:
+        The system prompt string (without agent.md content)
+    """
+    return f"""### Current Working Directory
+
+The filesystem backend is currently operating in: `{Path.cwd()}`
+
+### Memory System Reminder
+
+Your long-term memory is stored in /memories/ and persists across sessions.
+
+**IMPORTANT - Check memories before answering:**
+- When asked "what do you know about X?" → Run `ls /memories/` FIRST, then read relevant files
+- When starting a task → Check if you have guides or examples in /memories/
+- At the beginning of new sessions → Consider checking `ls /memories/` to see what context you have
+
+Base your answers on saved knowledge (from /memories/) when available, supplemented by general knowledge.
+
+### Human-in-the-Loop Tool Approval
+
+Some tool calls require user approval before execution. When a tool call is rejected by the user:
+1. Accept their decision immediately - do NOT retry the same command
+2. Explain that you understand they rejected the action
+3. Suggest an alternative approach or ask for clarification
+4. Never attempt the exact same rejected command again
+
+Respect the user's decisions and work with them collaboratively.
+
+### Web Search Tool Usage
+
+When you use the web_search tool:
+1. The tool will return search results with titles, URLs, and content excerpts
+2. You MUST read and process these results, then respond naturally to the user
+3. NEVER show raw JSON or tool results directly to the user
+4. Synthesize the information from multiple sources into a coherent answer
+5. Cite your sources by mentioning page titles or URLs when relevant
+6. If the search doesn't find what you need, explain what you found and ask clarifying questions
+
+The user only sees your text responses - not tool results. Always provide a complete, natural language answer after using web_search.
+
+### Todo List Management
+
+When using the write_todos tool:
+1. Keep the todo list MINIMAL - aim for 3-6 items maximum
+2. Only create todos for complex, multi-step tasks that truly need tracking
+3. Break down work into clear, actionable items without over-fragmenting
+4. For simple tasks (1-2 steps), just do them directly without creating todos
+5. When first creating a todo list for a task, ALWAYS ask the user if the plan looks good before starting work
+   - Create the todos, let them render, then ask: "Does this plan look good?" or similar
+   - Wait for the user's response before marking the first todo as in_progress
+   - If they want changes, adjust the plan accordingly
+6. Update todo status promptly as you complete each item
+
+The todo list is a planning tool - use it judiciously to avoid overwhelming the user with excessive task tracking."""
+
+
+def create_agent_with_config(model, assistant_id: str, tools: list):
+    """Create and configure an agent with the specified model and tools."""
+    shell_middleware = ResumableShellToolMiddleware(
+        workspace_root=os.getcwd(), execution_policy=HostExecutionPolicy()
+    )
+
+    # For long-term memory, point to ~/.deepagents/AGENT_NAME/ with /memories/ prefix
+    agent_dir = Path.home() / ".deepagents" / assistant_id
+    agent_dir.mkdir(parents=True, exist_ok=True)
+    agent_md = agent_dir / "agent.md"
+    if not agent_md.exists():
+        source_content = get_default_coding_instructions()
+        agent_md.write_text(source_content)
+
+    # Long-term backend - rooted at agent directory
+    # This handles both /memories/ files and /agent.md
+    long_term_backend = FilesystemBackend(root_dir=agent_dir, virtual_mode=True)
+
+    # Composite backend: current working directory for default, agent directory for /memories/
+    backend = CompositeBackend(
+        default=FilesystemBackend(), routes={"/memories/": long_term_backend}
+    )
+
+    # Use the same backend for agent memory middleware
+    agent_middleware = [
+        AgentMemoryMiddleware(backend=long_term_backend, memory_path="/memories/"),
+        shell_middleware,
+    ]
+
+    # Get the system prompt
+    system_prompt = get_system_prompt()
+
+    # Helper functions for formatting tool descriptions in HITL prompts
+    def format_write_file_description(tool_call: dict) -> str:
+        """Format write_file tool call for approval prompt."""
+        args = tool_call.get("args", {})
+        file_path = args.get("file_path", "unknown")
+        content = args.get("content", "")
+
+        action = "Overwrite" if os.path.exists(file_path) else "Create"
+        line_count = len(content.splitlines())
+        size = len(content.encode("utf-8"))
+
+        return f"File: {file_path}\nAction: {action} file\nLines: {line_count} · Bytes: {size}"
+
+    def format_edit_file_description(tool_call: dict) -> str:
+        """Format edit_file tool call for approval prompt."""
+        args = tool_call.get("args", {})
+        file_path = args.get("file_path", "unknown")
+        old_string = args.get("old_string", "")
+        new_string = args.get("new_string", "")
+        replace_all = bool(args.get("replace_all", False))
+
+        delta = len(new_string) - len(old_string)
+
+        return (
+            f"File: {file_path}\n"
+            f"Action: Replace text ({'all occurrences' if replace_all else 'single occurrence'})\n"
+            f"Snippet delta: {delta:+} characters"
+        )
+
+    def format_web_search_description(tool_call: dict) -> str:
+        """Format web_search tool call for approval prompt."""
+        args = tool_call.get("args", {})
+        query = args.get("query", "unknown")
+        max_results = args.get("max_results", 5)
+
+        return f"Query: {query}\nMax results: {max_results}\n\n⚠️  This will use Tavily API credits"
+
+    def format_task_description(tool_call: dict) -> str:
+        """Format task (subagent) tool call for approval prompt."""
+        args = tool_call.get("args", {})
+        description = args.get("description", "unknown")
+        prompt = args.get("prompt", "")
+
+        # Truncate prompt if too long
+        prompt_preview = prompt[:300]
+        if len(prompt) > 300:
+            prompt_preview += "..."
+
+        return (
+            f"Task: {description}\n\n"
+            f"Instructions to subagent:\n"
+            f"{'─' * 40}\n"
+            f"{prompt_preview}\n"
+            f"{'─' * 40}\n\n"
+            f"⚠️  Subagent will have access to file operations and shell commands"
+        )
+
+    # Configure human-in-the-loop for potentially destructive tools
+    from langchain.agents.middleware import InterruptOnConfig
+
+    shell_interrupt_config: InterruptOnConfig = {
+        "allowed_decisions": ["approve", "reject"],
+        "description": lambda tool_call, state, runtime: (
+            f"Shell Command: {tool_call['args'].get('command', 'N/A')}\n"
+            f"Working Directory: {os.getcwd()}"
+        ),
+    }
+
+    write_file_interrupt_config: InterruptOnConfig = {
+        "allowed_decisions": ["approve", "reject"],
+        "description": lambda tool_call, state, runtime: format_write_file_description(tool_call),
+    }
+
+    edit_file_interrupt_config: InterruptOnConfig = {
+        "allowed_decisions": ["approve", "reject"],
+        "description": lambda tool_call, state, runtime: format_edit_file_description(tool_call),
+    }
+
+    web_search_interrupt_config: InterruptOnConfig = {
+        "allowed_decisions": ["approve", "reject"],
+        "description": lambda tool_call, state, runtime: format_web_search_description(tool_call),
+    }
+
+    task_interrupt_config: InterruptOnConfig = {
+        "allowed_decisions": ["approve", "reject"],
+        "description": lambda tool_call, state, runtime: format_task_description(tool_call),
+    }
+
+    agent = create_deep_agent(
+        model=model,
+        system_prompt=system_prompt,
+        tools=tools,
+        backend=backend,
+        middleware=agent_middleware,
+        interrupt_on={
+            "shell": shell_interrupt_config,
+            "write_file": write_file_interrupt_config,
+            "edit_file": edit_file_interrupt_config,
+            "web_search": web_search_interrupt_config,
+            "task": task_interrupt_config,
+        },
+    ).with_config(config)
+
+    agent.checkpointer = InMemorySaver()
+
+    return agent

deepagents_cli/cli.py

@@ -0,0 +1,13 @@
+"""Main CLI entrypoint for deepagents."""
+
+
+def cli_main() -> None:
+    """Main entrypoint for the deepagents CLI.
+
+    This function is registered as a console script entrypoint in pyproject.toml.
+    """
+    print("I'm alive!")
+
+
+if __name__ == "__main__":
+    cli_main()

deepagents_cli/commands.py

@@ -0,0 +1,89 @@
+"""Command handlers for slash commands and bash execution."""
+
+import subprocess
+from pathlib import Path
+
+from langgraph.checkpoint.memory import InMemorySaver
+
+from .config import COLORS, DEEP_AGENTS_ASCII, console
+from .ui import TokenTracker, show_interactive_help
+
+
+def handle_command(command: str, agent, token_tracker: TokenTracker) -> str | bool:
+    """Handle slash commands. Returns 'exit' to exit, True if handled, False to pass to agent."""
+    cmd = command.lower().strip().lstrip("/")
+
+    if cmd in ["quit", "exit", "q"]:
+        return "exit"
+
+    if cmd == "clear":
+        # Reset agent conversation state
+        agent.checkpointer = InMemorySaver()
+
+        # Reset token tracking to baseline
+        token_tracker.reset()
+
+        # Clear screen and show fresh UI
+        console.clear()
+        console.print(DEEP_AGENTS_ASCII, style=f"bold {COLORS['primary']}")
+        console.print()
+        console.print(
+            "... Fresh start! Screen cleared and conversation reset.", style=COLORS["agent"]
+        )
+        console.print()
+        return True
+
+    if cmd == "help":
+        show_interactive_help()
+        return True
+
+    if cmd == "tokens":
+        token_tracker.display_session()
+        return True
+
+    console.print()
+    console.print(f"[yellow]Unknown command: /{cmd}[/yellow]")
+    console.print("[dim]Type /help for available commands.[/dim]")
+    console.print()
+    return True
+
+    return False
+
+
+def execute_bash_command(command: str) -> bool:
+    """Execute a bash command and display output. Returns True if handled."""
+    cmd = command.strip().lstrip("!")
+
+    if not cmd:
+        return True
+
+    try:
+        console.print()
+        console.print(f"[dim]$ {cmd}[/dim]")
+
+        # Execute the command
+        result = subprocess.run(
+            cmd, check=False, shell=True, capture_output=True, text=True, timeout=30, cwd=Path.cwd()
+        )
+
+        # Display output
+        if result.stdout:
+            console.print(result.stdout, style=COLORS["dim"], markup=False)
+        if result.stderr:
+            console.print(result.stderr, style="red", markup=False)
+
+        # Show return code if non-zero
+        if result.returncode != 0:
+            console.print(f"[dim]Exit code: {result.returncode}[/dim]")
+
+        console.print()
+        return True
+
+    except subprocess.TimeoutExpired:
+        console.print("[red]Command timed out after 30 seconds[/red]")
+        console.print()
+        return True
+    except Exception as e:
+        console.print(f"[red]Error executing command: {e}[/red]")
+        console.print()
+        return True

deepagents_cli/config.py

@@ -0,0 +1,138 @@
+"""Configuration, constants, and model creation for the CLI."""
+
+import os
+import sys
+from pathlib import Path
+
+import dotenv
+from rich.console import Console
+
+dotenv.load_dotenv()
+
+# Color scheme
+COLORS = {
+    "primary": "#10b981",
+    "dim": "#6b7280",
+    "user": "#ffffff",
+    "agent": "#10b981",
+    "thinking": "#34d399",
+    "tool": "#fbbf24",
+}
+
+# ASCII art banner
+DEEP_AGENTS_ASCII = """
+ ██████╗  ███████╗ ███████╗ ██████╗
+ ██╔══██╗ ██╔════╝ ██╔════╝ ██╔══██╗
+ ██║  ██║ █████╗   █████╗   ██████╔╝
+ ██║  ██║ ██╔══╝   ██╔══╝   ██╔═══╝
+ ██████╔╝ ███████╗ ███████╗ ██║
+ ╚═════╝  ╚══════╝ ╚══════╝ ╚═╝
+
+  █████╗   ██████╗  ███████╗ ███╗   ██╗ ████████╗ ███████╗
+ ██╔══██╗ ██╔════╝  ██╔════╝ ████╗  ██║ ╚══██╔══╝ ██╔════╝
+ ███████║ ██║  ███╗ █████╗   ██╔██╗ ██║    ██║    ███████╗
+ ██╔══██║ ██║   ██║ ██╔══╝   ██║╚██╗██║    ██║    ╚════██║
+ ██║  ██║ ╚██████╔╝ ███████╗ ██║ ╚████║    ██║    ███████║
+ ╚═╝  ╚═╝  ╚═════╝  ╚══════╝ ╚═╝  ╚═══╝    ╚═╝    ╚══════╝
+"""
+
+# Interactive commands
+COMMANDS = {
+    "clear": "Clear screen and reset conversation",
+    "help": "Show help information",
+    "tokens": "Show token usage for current session",
+    "quit": "Exit the CLI",
+    "exit": "Exit the CLI",
+}
+
+# Common bash commands for autocomplete
+COMMON_BASH_COMMANDS = {
+    "ls": "List directory contents",
+    "ls -la": "List all files with details",
+    "cd": "Change directory",
+    "pwd": "Print working directory",
+    "cat": "Display file contents",
+    "grep": "Search text patterns",
+    "find": "Find files",
+    "mkdir": "Make directory",
+    "rm": "Remove file",
+    "cp": "Copy file",
+    "mv": "Move/rename file",
+    "echo": "Print text",
+    "touch": "Create empty file",
+    "head": "Show first lines",
+    "tail": "Show last lines",
+    "wc": "Count lines/words",
+    "chmod": "Change permissions",
+}
+
+# Maximum argument length for display
+MAX_ARG_LENGTH = 150
+
+# Agent configuration
+config = {"recursion_limit": 1000}
+
+# Rich console instance
+console = Console(highlight=False)
+
+
+class SessionState:
+    """Holds mutable session state (auto-approve mode, etc)."""
+
+    def __init__(self, auto_approve: bool = False):
+        self.auto_approve = auto_approve
+
+    def toggle_auto_approve(self) -> bool:
+        """Toggle auto-approve and return new state."""
+        self.auto_approve = not self.auto_approve
+        return self.auto_approve
+
+
+def get_default_coding_instructions() -> str:
+    """Get the default coding agent instructions.
+
+    These are the immutable base instructions that cannot be modified by the agent.
+    Long-term memory (agent.md) is handled separately by the middleware.
+    """
+    default_prompt_path = Path(__file__).parent.parent / "default_agent_prompt.md"
+    return default_prompt_path.read_text()
+
+
+def create_model():
+    """Create the appropriate model based on available API keys.
+
+    Returns:
+        ChatModel instance (OpenAI or Anthropic)
+
+    Raises:
+        SystemExit if no API key is configured
+    """
+    openai_key = os.environ.get("OPENAI_API_KEY")
+    anthropic_key = os.environ.get("ANTHROPIC_API_KEY")
+
+    if openai_key:
+        from langchain_openai import ChatOpenAI
+
+        model_name = os.environ.get("OPENAI_MODEL", "gpt-5-mini")
+        console.print(f"[dim]Using OpenAI model: {model_name}[/dim]")
+        return ChatOpenAI(
+            model=model_name,
+            temperature=0.7,
+        )
+    if anthropic_key:
+        from langchain_anthropic import ChatAnthropic
+
+        model_name = os.environ.get("ANTHROPIC_MODEL", "claude-sonnet-4-5-20250929")
+        console.print(f"[dim]Using Anthropic model: {model_name}[/dim]")
+        return ChatAnthropic(
+            model_name=model_name,
+            max_tokens=20000,
+        )
+    console.print("[bold red]Error:[/bold red] No API key configured.")
+    console.print("\nPlease set one of the following environment variables:")
+    console.print("  - OPENAI_API_KEY     (for OpenAI models like gpt-5-mini)")
+    console.print("  - ANTHROPIC_API_KEY  (for Claude models)")
+    console.print("\nExample:")
+    console.print("  export OPENAI_API_KEY=your_api_key_here")
+    console.print("\nOr add it to your .env file.")
+    sys.exit(1)