CLI & TUI User Guide

Arcen Agent supports two local interface modes: a classic interactive CLI built with prompt_toolkit and Rich, and an Ink-based TUI.

1. CLI Commands & Slash Commands

Launch the classic interactive session:

arcen

Slash Command Registry

All slash commands are registered centrally as CommandDef entries in arcen_cli/commands.py. This ensures autocomplete, help pages, Slack routing, and Telegram menus stay in sync automatically.

To add or modify a command:

Define a CommandDef in arcen_cli/commands.py:

CommandDef(
    name="background",
    description="Put the current task in the background",
    category="Session",
    aliases=("bg", "detach"),
    args_hint="[task_id]",
)

Add a command handler in ArcenCLI.process_command() in cli.py:

elif canonical == "background":
    self._handle_background(cmd_original)

If the command runs remotely, register its handler in gateway/run.py as well.

Common Slash Commands

Command	Category	Description
`/new` (or `/reset`)	Session	Reset the conversation history and start a new session.
`/model [provider:model]`	Session	Switch model and provider for the active session.
`/usage`	Session	View current token counts and budget limits.
`/skills`	Tools	List available built-in and optional skills.
`/skin [name]`	Config	Switch the active terminal visual theme.
`/quit`	Exit	Terminate the CLI.

2. TUI Architecture

The Terminal User Interface (TUI) replaces the classic prompt-toolkit shell. Launch it with:

arcen --tui
# or
ARCEN_TUI=1 arcen

Process Model

The TUI is structured as two separate processes communicating over standard input/output:

┌────────────────────────────────┐
│         Node (Ink UI)          │   TypeScript owns the screen, rendering
│   (Transcripts, Prompts, etc.) │   the transcript, composer, and status logs.
└───────────────┬────────────────┘
                │
         stdio JSON-RPC
                │
┌───────────────▼────────────────┐
│      Python (tui_gateway)      │   Python manages AIAgent iterations, session DB
│   (AIAgent, Tools, Sessions)   │   records, tool registry checks, and LLM calls.
└────────────────────────────────┘

3. Local TUI Development

The TUI is built using React, Ink, and TypeScript in the ui-tui directory.

Development Commands

cd ui-tui
npm install        # Install Node dependencies
npm run dev        # Run in watch mode (compiles ink and updates on change)
npm run build      # Full production build compiling assets
npm run type-check # Run TypeScript checks without building
npm test           # Execute Vitest test suites

TypeScript and State Style Rules

When developing for the TUI, follow these architectural constraints:

State Management: Use small, focused nanostores rather than monolithic React component state when state is shared or accessed by distant components.
Store Subscriptions: Components rendering from an atom should use useStore(atom). Pure logic handlers should read state using $atom.get() instead of subscribing.
Asynchronous Handlers: Async UI triggers should return void explicitly:
```
onClick={() => void save()}
```

Type Interfaces: Prefer interface rather than type intersections for public component props:

interface ButtonProps extends React.ComponentProps<'button'> {
  variant?: 'primary' | 'secondary';
}

Routing & Routing Roots: Keep route entry files thin. They are controllers for composing child routes and layout shells; business logic belongs in separate packages.