The Terminal-First Philosophy

1# Works on your laptop
2$ claude "Add rate limiting to the API"
3
4# Works over SSH to your server
5$ ssh production
6$ claude "Debug why the cache is failing"
7
8# Works in a docker container
9$ docker exec -it app claude "Optimize the database queries"
10
11# Works in CI/CD
12$ claude --headless "Generate release notes from recent commits"

1# Pipe output to other tools
2$ claude "List the API endpoints" | grep -i auth
3
4# Use in scripts
5for file in src/**/*.ts; do
6  claude "Add JSDoc comments to $file"
7done
8
9# Combine with other CLI tools
10$ git diff HEAD~5 | claude "Summarize these changes"
11
12# Run in parallel
13$ parallel claude "Document {}" ::: src/utils/*.ts

1# IDE plugins must:
2# - Load into IDE memory space
3# - Handle IDE events and callbacks
4# - Manage complex UI state
5# - Stay synchronized with editor
6
7# Terminal agents:
8# - Start fresh each invocation (or continue from history)
9# - Use only the memory they need
10# - No UI overhead
11# - Can exit cleanly when done

1# All output is visible and capturable
2$ claude "Fix the auth bug" 2>&1 | tee debug.log
3
4# Verbose mode shows internal reasoning
5$ claude --verbose "Refactor the API"
6
7# Inspect the exact commands being run
8$ claude --show-tools "Deploy to staging"
9
10# Replay a session for debugging
11$ claude --replay session-123

1from rich.console import Console
2from rich.markdown import Markdown
3from rich.panel import Panel
4from rich.syntax import Syntax
5
6console = Console()
7
8def display_agent_response(response: AgentResponse):
9    """Display agent response with rich formatting."""
10
11    # Show reasoning in a panel
12    if response.reasoning:
13        console.print(Panel(
14            response.reasoning,
15            title="[bold blue]Thinking...[/]",
16            border_style="blue",
17        ))
18
19    # Show tool calls
20    for tool_call in response.tool_calls:
21        console.print(f"[yellow]→ {tool_call.name}[/]")
22        if tool_call.name == "read_file":
23            console.print(f"  Reading: {tool_call.params['path']}")
24        elif tool_call.name == "write_file":
25            console.print(f"  Writing: {tool_call.params['path']}")
26            # Show diff
27            show_diff(tool_call.params)
28
29    # Show final response
30    if response.text:
31        console.print(Markdown(response.text))

1from rich.prompt import Confirm, Prompt
2
3def request_permission(action: str, details: str) -> bool:
4    """Request user permission for an action."""
5    console.print(Panel(
6        f"[yellow]{action}[/]\n\n{details}",
7        title="[bold red]Permission Required[/]",
8    ))
9
10    return Confirm.ask("Allow this action?")
11
12def get_clarification(question: str, options: list[str]) -> str:
13    """Get user clarification with options."""
14    console.print(f"\n[bold]{question}[/]\n")
15
16    for i, option in enumerate(options, 1):
17        console.print(f"  {i}. {option}")
18
19    return Prompt.ask(
20        "Select option",
21        choices=[str(i) for i in range(1, len(options) + 1)],
22    )

1from rich.progress import Progress, SpinnerColumn, TextColumn
2from rich.live import Live
3
4def run_agent_with_progress(agent, goal: str):
5    """Run agent with live progress updates."""
6
7    with Progress(
8        SpinnerColumn(),
9        TextColumn("[progress.description]{task.description}"),
10        transient=True,
11    ) as progress:
12        task = progress.add_task("Starting...", total=None)
13
14        for step in agent.run_iter(goal):
15            progress.update(task, description=step.description)
16
17            if step.type == "tool_call":
18                console.print(f"[dim]→ {step.tool_name}[/]")
19            elif step.type == "observation":
20                console.print(step.observation[:100])
21
22    console.print("[green]✓[/] Complete")

1async def stream_response(agent, goal: str):
2    """Stream agent response as it's generated."""
3
4    async for chunk in agent.stream(goal):
5        if chunk.type == "text":
6            console.print(chunk.text, end="")
7        elif chunk.type == "tool_start":
8            console.print(f"\n[yellow]→ {chunk.tool_name}[/]", end="")
9        elif chunk.type == "tool_end":
10            console.print(f" [green]✓[/]")
11
12    console.print()  # Final newline

1# Default view: summary
2$ claude "Refactor the API"
3✓ Read 5 files
4✓ Modified 3 files
5✓ Tests passing
6
7# Verbose view: full details
8$ claude --verbose "Refactor the API"
9→ read_file(src/api/routes.ts)
10  [250 lines of content...]
11→ read_file(src/api/handlers.ts)
12  [180 lines of content...]
13...

1→  Action in progress
2✓  Success
3✗  Failed
4⚠  Warning/needs attention
5?  Waiting for input
6↩  Undoing previous action
7
8[dim] gray text for less important info
9[yellow] highlights for actions
10[red] errors and warnings
11[green] success confirmations