iii Experimental Agent

Local-first experimental agent stack for iii.

This repo is intentionally narrow:

• No engine changes.
• No claims before the local TUI/CLI can prove them.
• No standalone agent framework.
• Agent UX is a composition of iii workers.
• Capabilities are installed as workers: iii worker add <capability>.
• New work happens here only when existing workers cannot satisfy the need.

Thesis

An agent surface should compose existing capabilities, not invent new ones. iii already ships the substrate (HTTP, queue, stream, pubsub, state, observability, cron, shell, bridge, sandbox), so this repo wires a chat client on top of it without growing a parallel framework.

Built-in/base iii workers already cover:

• HTTP/rest-api
• queue
• stream/pubsub
• state
• observability/telemetry
• cron
• shell/exec
• bridge-client
• sandbox/runtime support

External ecosystem capabilities are added only when needed:

iii worker add mcp
iii worker add shell-filesystem
iii worker add turn-orchestrator
iii worker add session-tree

Then the TUI/CLI discovers and uses those capabilities through iii functions/triggers.

Current phase

Local only.

We are not publishing claims yet. The goal is to make the local stack compelling first:

1. Start from iii builtin/base workers.
2. Reuse iii-hq/workers for external ecosystem capabilities.
3. Reuse the existing harness worker and its worker graph where possible.
4. Run local demos from source until registry publishing catches up.
5. Build only missing glue/workers in this repo.
6. Promote to public ecosystem language only after the TUI/CLI is actually capable.

Important source repos

• Engine/runtime: iii-hq/iii
• Worker ecosystem: iii-hq/workers
• This experimental composition: iii-experimental/agent

Recommended portable local layout:

workspace/
  agent/    # this folder
  iii/      # cloned iii-hq/iii
  workers/  # cloned iii-hq/workers

The scripts default to that sibling layout. If your checkouts live elsewhere, set III_ROOT=/path/to/iii and WORKERS_DIR=/path/to/workers.

Local worker baseline

The existing iii-hq/workers/harness worker composes:

• turn-orchestrator
• provider-router
• session-tree
• session-inbox
• models-catalog
• hook-fanout
• policy-denylist
• shell
• subagent
• provider-anthropic
• provider-openai
• auth-credentials
• llm-budget
• skills
• approval-gate
• iii-sandbox

It exposes:

• harness::status
• bridge::trigger
• bridge::events

Caution: bridge::trigger is browser/control-plane only, not an LLM tool.

Local-first commands

From this repo:

./scripts/bootstrap-local-workers.sh
./scripts/local-stack-check.sh

# Inspection
./bin/iii-agent inventory
./bin/iii-agent status
./bin/iii-agent plan --capability queue --capability mcp --capability approval-gate

# Phase 2 — capability UX
./bin/iii-agent capabilities list
./bin/iii-agent capabilities search mcp
./bin/iii-agent capabilities inspect shell-bash
./bin/iii-agent capabilities add mcp

# Functions
./bin/iii-agent functions list
./bin/iii-agent functions search shell
./bin/iii-agent functions inspect shell::exec
./bin/iii-agent functions call engine::workers::list --payload '{}'

# Sessions + approvals
./bin/iii-agent sessions list
./bin/iii-agent sessions view <session_id>
./bin/iii-agent approvals list
./bin/iii-agent approvals resolve <id> --approve

# Build + run every local backend worker (introspection + skills-loader)
./scripts/build-workers.sh build
./scripts/build-workers.sh run

# Chat surface — ratatui TUI (multi-panel) or REPL (line-mode)
./scripts/run-tui.sh                              # builds workers/harness-tui on first run
./bin/iii-chat
./bin/iii-chat --prompt "describe the shell-bash worker"

# Underlying scripts (callable directly)
./scripts/capability-inventory.py
./scripts/capability-plan.py --capability queue --capability mcp --capability approval-gate
./scripts/capability-status.py
./scripts/capability-functions.py list
./scripts/capability-capabilities.py list
./scripts/capability-sessions.py list
./scripts/capability-approvals.py list
./scripts/run-harness-local.sh verify

Harness demo commands, assuming the sibling workers/ checkout:

cd ../workers/harness
./scripts/demo.sh build
./scripts/demo.sh engine
./scripts/demo.sh start
./scripts/demo.sh verify
./scripts/demo.sh web

Share to another device

See docs/local-agent-worker-pack.md for the full worker table and transfer flow.

Create a portable folder and tarball:

./scripts/package-local-agent.sh

Copy the generated dist/iii-agent-local-*.tar.gz to the other device and unpack it into a workspace:

mkdir -p ~/iii-agent-workspace
cd ~/iii-agent-workspace
tar -xzf /path/to/iii-agent-local-*.tar.gz
mv iii-agent-local agent
cd agent
./scripts/bootstrap-local-workers.sh
./scripts/local-stack-check.sh

Then clone/build the engine beside it if needed:

cd ~/iii-agent-workspace
git clone https://github.com/iii-hq/iii.git iii
cd iii
cargo build -p iii --bin iii

The folder stays local-first: no engine source changes, no separate agent framework, and capabilities are normal iii workers/functions/triggers.

Product boundary

This is a local experimental iii agent stack composed from workers. Status: 0.x experimental. Not production-ready. APIs may shift until the TUI/CLI flow is stable end-to-end.

Development rule

If a capability already exists in iii-hq/workers, reuse it.

If it is not published in the registry yet, run it locally from source.

If it does not exist, create a small worker here and document the eventual path to iii-hq/workers.

Local workers + client in this repo

Path	Kind	Purpose
workers/introspection	worker	iii-introspection — slim/just-in-time engine introspection (workers::list/describe, functions::list/describe, stream::subscribe, registry::query).
workers/skills-loader	worker	iii-skills-loader — progressive-disclosure skills index (skills::index, skills::load, skills::rescan). Multi-root SKILL.md walker, interops with ~/.claude/skills and ~/.codex/skills.
workers/harness-tui	client (not a worker)	iii-harness-tui — local ratatui chat client. Discovers tools via introspection::*, tracks tokens via budget::*, drives chat turns via run::start_and_wait. Lives in this repo so the experience is fully owned and reproducible — no dependency on iii-experimental/harness.

Build + run both:

./scripts/build-workers.sh build
./scripts/build-workers.sh run        # foreground via nohup, pids in .iii-agent/pids
./scripts/build-workers.sh stop
./scripts/build-workers.sh restart

Both workers ship the canonical files required by iii-hq/workers CI: iii.worker.yaml (v1, name, language, deploy, manifest, bin), top-level skill.md, and tests/integration.rs. Promotion is a copy + registry/index.json update.

Chat surfaces

Two interchangeable surfaces, both backed by the same iii engine + workers:

./scripts/install-iii.sh             # fresh install: engine + harness binaries + workers checkout
./scripts/build-workers.sh restart   # build + run introspection + skills-loader (background)

# Full ratatui TUI — multi-panel: chat, tokens, workers, status
./scripts/run-tui.sh                 # builds workers/harness-tui on first run, then launches

# Line-mode REPL (no ratatui, plain stdout)
./bin/iii-chat                       # interactive REPL
./bin/iii-chat --prompt "list my workers"   # one-shot

Both expose the same slash commands: /help, /functions [q], /describe <id>, /workers, /skills [q], /skill <id>, /budget, /clear, /quit. Token usage shows in the TUI side panel live and prints after every REPL turn (driven by budget::get_usage).