# `Agent Smith` coding agent

![Agent Smith logo](images/agent_logo.png)

## Overview

_Agent Smith_ is the coding agent mode for Lilush Shell.

::: caution

_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:

```lsh
lilpack install agent_smith
```

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

```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`.

The `web_search` tool uses [Linkup](https://docs.linkup.so) as its default backend,
reading its API key from the `LINKUP_API_KEY` env var. Defaults
(`api_key_env`, `endpoint`, `depth`, `output_type`, `max_results`, `timeout`)
can be overridden via the `services.tool.web_search` config block.

### Minimal config example

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

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

Tested backends:  
- [GoModel](https://github.com/ENTERPILOT/GOModel) 
- [llama-server](https://github.com/ggml-org/llama.cpp/tree/master/tools/server)

For the complete default config, the config schema, per-model maps, and the LLM
timeout/retry fields, see [ARCHITECTURE.md](docs/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 between direct and orchestrator mode at runtime with `Shift+Tab`.

This shortcut basically does the following:
```lsh
/config set active_role orchestrator|direct
/new
```

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](docs/ARCHITECTURE.md#roles) 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).

## Documentation map

- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — runtime/services/contracts, config, roles, tools, dispatch, events, completions, UI.
- [LLM.md](docs/LLM.md) — embedded LLM client/tool/model contracts.
- [USER_COMMANDS.md](docs/USER_COMMANDS.md) — user-defined command files.