Interactive CLI Entrypoint

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cea/src/entrypoints/cli.ts
• packages/cea/src/entrypoints/AGENTS.md
• packages/tui/src/agent-tui.ts
• packages/cea/src/AGENTS.md
• AGENTS.md
• packages/minimal-agent/index.ts
• packages/cea/src/context/system-prompt.ts

The Interactive CLI Entrypoint serves as the primary human-facing interface for the plugsuits project. It provides a Terminal User Interface (TUI) that enables users to interact with AI agents through a conversational loop, allowing for real-time code editing, shell execution, and file exploration. This entrypoint is implemented as a runtime wrapper around the core agent harness, specifically designed to handle terminal rendering, interactive input, and session management.

Sources: packages/cea/src/entrypoints/AGENTS.md, packages/cea/src/AGENTS.md, README.md:30-40

Architecture and Interaction Loop

The CLI entrypoint operates on a continuous "Input-Process-Output" lifecycle managed primarily within src/entrypoints/cli.ts. It utilizes the @ai-sdk-tool/tui package to render the interface and @ai-sdk-tool/harness to manage the underlying agent logic and conversation history.

Lifecycle Stages

1. Run Initialization: Bootstraps the session, initializes tools, and sets up the environment.
2. Process Input: Captures user text or slash commands via an interactive editor.
3. Agent Stream Processing: Handles the incoming stream from the AI model, rendering text and tool calls as they arrive.
4. Tool Loop Execution: Automatically executes tools requested by the model and feeds results back into the loop if the finish reason indicates more steps are needed.

Sources: packages/cea/src/AGENTS.md:23-28, packages/cea/src/entrypoints/AGENTS.md:12-16

Core Components

The Interactive CLI is composed of several specialized modules that coordinate to provide a seamless terminal experience.

Session and History Management

The entrypoint maintains state through a SessionManager for UUID-based session tracking and a CheckpointHistory instance for conversation persistence. It also integrates a CompactionOrchestrator to manage context limits, ensuring the conversation remains within the model's token constraints through automated summarization.

Sources: AGENTS.md:46-55, packages/minimal-agent/index.ts:114-125

Slash Commands

Users can control the CLI environment using slash commands. These commands allow for session resets, model switching, and manual history compaction.

Command	Aliases	Description
/help	-	Shows the help message and available commands
/clear	/reset, /new	Resets the conversation and starts a new session
/compact	-	Manually triggers the history compaction process
/model	-	Switches the active AI model
/quit	-	Gracefully exits the CLI

Sources: README.md:58-70, packages/minimal-agent/index.ts:77-96

Tool Loop Control and Continuation

A critical feature of the interactive entrypoint is its ability to handle "Manual Tool Loops." When an agent requests a tool (e.g., read_file or shell_execute), the entrypoint manages the execution and decides whether to return control to the user or continue the agent's turn.

Continuation Policy

The CLI shares a continuation policy with the headless mode via the shouldContinueManualToolLoop predicate. It typically continues execution automatically if:

• The model's finish reason is tool-calls.
• The number of sequential tool steps has not exceeded MANUAL_TOOL_LOOP_MAX_STEPS.

Sources: packages/cea/src/entrypoints/AGENTS.md:20-25, AGENTS.md:56-57

TUI Rendering Implementation

The visual representation is handled by createAgentTUI, which wires the following views:

• AssistantStreamView: Renders streaming markdown text and internal "reasoning" segments with distinct styling.
• BaseToolCallView: Displays tool inputs as they are generated and provides real-time feedback on tool outputs or errors.
• Footer: Dynamically displays context usage (e.g., 12.4k/128k tokens) and session status.

Sources: packages/tui/AGENTS.md:51-65, packages/minimal-agent/index.ts:153-165

Technical Constraints

• Signal Handling: The entrypoint registers handlers for SIGINT (Ctrl+C) and SIGTERM to ensure graceful cleanup of background processes and session data.
• Tool Safety: While in interactive mode, the system prompt encourages the agent to "Understand Before Acting" by reading files before editing them.
• Environment: All configuration and API keys are validated through a Zod-based schema in env.ts before the loop starts.

Sources: packages/cea/src/context/system-prompt.ts:117-122, packages/cea/src/entrypoints/AGENTS.md:24-25, AGENTS.md:83-88

Summary

The Interactive CLI Entrypoint is a robust, session-aware terminal interface that bridges the gap between AI models and local development environments. By combining real-time TUI rendering with automated tool-loop logic and proactive context management, it enables a highly autonomous yet user-controllable coding assistant experience. Its architecture ensures parity with headless automation while providing the rich feedback necessary for interactive software engineering tasks.