Agent Smith coding agent

Overview

Agent Smith is the coding agent mode for Lilush Shell.

Agent Smith, by default and by design, works in YOLO mode: tool use is auto-approved, there are no guardrails in bash tool, etc.

Thus the only reasonably safe way to run it is in an ephemeral environment, i.e. an environment that is easily reproducible/respawnable, sufficiently restricted and isolated.

In practical terms, that would be, for example, a QEMU VM, deployed with strict adherence to the PoLP.

Anything less than that will most probably result in data loss. You have been warned.

Install

From Lilush Shell:

lilpack install agent_smith

Add agent mode keybind in ~/.config/lilush/modes.json:

{ "F4": "agent_smith" }

and restart the shell.

Configure

User config is read from ~/.config/lilush/agent_smith.json and merged on top of the built-in defaults — you only need to specify what you want to change.

The API key is read from LLM_API_KEY env var by default, configurable via llm_config.api_key_env.

Minimal config example

Assuming you have a OpenAI ChatCompletions API compatible LLM-server/gateway running at 192.168.3.24:

{
  "active_role": "orchestrator",
  "llm_config": {
    "api_url": "http://192.168.3.24:8090/v1"
  }
}

Tested backends:

For the complete default config, the config schema, per-model maps, and the LLM timeout/retry fields, see ARCHITECTURE.md.

Roles & modes

There are four roles:

Role name	Role alias	User-facing
direct	Smith	yes
orchestrator	Tank	yes
explorer	Link	no
worker	Niobe	no

Agent Smith runs in one of two user-facing modes, set by the active role. The mode determines how the agent works on your behalf — hands-on, or by planning and delegating.

Smith

Direct mode, active by default. A hands-on coding assistant.

It can read and edit files, write new ones, run shell commands, and search the web. It can also delegate sub-tasks when useful, but it doesn't have to.

Tank

Orchestrator mode. A planning-and-delegation layer.

It owns the conversation, clarifies the request, plans the work, and delegates execution to its child roles — synthesizing their results into a final answer. It deliberately cannot edit files or run shell commands itself; instead it keeps durable session notes (a scratchpad) and dispatches the actual changes.

Link and Niobe

Behind the scenes, both Smith and Tank can delegate to two internal child roles you never select directly: Niobe (a worker that implements changes) and Link (an explorer that investigates the codebase read-only).

Switching modes

Switch at runtime with:

/config set active_role orchestrator
/config set active_role direct

The choice is persisted across sessions. The default is direct.

What the agent can do

Depending on the active mode, the agent can:

run shell commands (bash)
read, edit, and write files
explore code with ignore-aware, ranked, budgeted tools (code_map, code_grep, code_files, code_symbols, code_outline) — available to every role, including the orchestrator
inspect git state read-only (git: status/log/diff/show/blame)
search and fetch from the web
remember project-specific notes across sessions
delegate focused sub-tasks to its child roles

The available tools depend on the active role. See ARCHITECTURE.md for the full tool set and the per-role permission matrix.

Conversation views

There are three conversation views:

Live view

This is the default view, with the interactive prompt line. In this view you type your queries, view responses and tool calls streaming live from the LLM.

Prompt line format

The interactive prompt displays the active role label, resolved model, working directory, and context window usage:

[Smith:<models.direct>] CWD (context window usage%) > — direct role
[Tank:<models.orchestrator>] CWD (context window usage%) > — orchestrator role

The model name (e.g. openrouter/qwen/qwen3.6-27b) appears once resolved from the models config map.

Pager view

This view is accessed via /pager slash command or Alt+h keyboard shortcut. In this view the whole conversation is displayed in the shell pager, where detailed tool call traces are replaced with compact summaries.

Inspect view

This view is accessed via /inspect slash command or Alt+i keyboard shortcut. In this view you can preview or open each individual message in the pager. You can also delete messages and edit content messages (i.e. not tool calls).

Slash commands

Session Management: /new, /clear, /history, /load, /usage
Configuration: /config, /config set, /config unset
Knowledge, Memory, Prompt: /memory, /scratchpad, /prompt
Conversation views: /pager, /inspect
User commands: /cmd list, /cmd show, /cmd <name>

Slash commands, /config paths, model ids, and role names tab-complete at the prompt (handled by the completion subsystem).