Extensions & memory

Add a skill

A skill is a directory containing a SKILL.md file with YAML metadata and Markdown instructions. PyLattice loads built-ins, plugin skills, workspace collections, and directories supplied with --skills-dir.

Create .agents/skills/project-review/SKILL.md in your workspace:

---
name: project-review
description: Review project changes and explain the checks performed.
---

Read the changed files and their callers.
Look for behavior changes and missing error handling.
Run focused checks and summarize findings with file references.

The name must match the directory and use lowercase letters, digits, and hyphens. .agent-tui/skills/ is also a supported workspace collection. Restart the app after adding a skill, then use:

/skills
/skill project-review
/skill off project-review

/skill NAME pins a workflow across tasks. Mention $project-review in a task to activate it for that task and related follow-ups. The agent receives a short catalog and can load relevant skills when needed.

Install plugin workflows

Use the plugin marketplace to add packaged skill collections:

/plugins
/plugin install superpowers
/skill superpowers:brainstorming

Use /plugin enable NAME, /plugin disable NAME, and /plugin uninstall NAME to manage installed plugins. Plugin skills use namespaced names in /skills.

Manage context and memory

The context manager builds task-relevant requests with a default 64,000-character budget. Persistent SQLite memory keeps workspace notes and run outcomes between sessions.

/context
/compact
/memory
/memory set test-command Run uv run pytest for the test suite.
/memory search test
/memory forget test-command

/compact shortens conversation history. Use --context-chars N to change the context budget and --no-memory to disable persistent memory. The offline demo also disables persistent memory.

Connect an MCP server

From the repository root, run the bundled server and hook configuration:

uv run agent-tui --extensions examples/extensions.toml

For your own configuration, use --extensions PATH or the default workspace file .agent-tui/extensions.toml. This minimal configuration starts the included stdio server:

[mcp_servers.example]
transport = "stdio"
command = "python"
args = ["examples/mcp_server.py"]
read_only_tools = ["add"]
timeout = 15

Command paths and arguments are relative to the workspace. The example path above assumes the PyLattice repository is the workspace. The agent requests approval to connect; /mcp shows server status. Only explicitly listed read_only_tools are treated as read-only.

Streamable HTTP servers use a URL and can read credentials from environment variables:

[mcp_servers.remote]
transport = "http"
url = "http://localhost:8000/mcp"
headers = { Authorization = "Bearer ${MCP_TOKEN}" }
timeout = 30

Replace the URL with your server endpoint and set MCP_TOKEN in your environment before connecting. A missing referenced environment variable is a configuration error.

Run middleware hooks

Hooks run commands on harness events. Add hook entries to the same extensions TOML file:

[[hooks]]
event = "before_tool"
command = ["python", "examples/hooks/protect_files.py"]
timeout = 5

[[hooks]]
event = "after_tool"
command = ["python", "examples/hooks/audit_log.py"]
timeout = 5

The bundled file policy blocks edits to lockfiles and production.env. The audit hook records event metadata. Commands run relative to the workspace and receive a JSON event on standard input; they can return a JSON object on standard output.

Command hooks require approval and are disabled in read-only mode. The approval preview uses the final tool arguments after hook changes. Use /hooks to inspect configured hooks.

Change the harness itself

Skills provide instructions, MCP adds tools, and hooks observe or adjust supported events. To replace a provider, prompt builder, tool registry, or other component, follow the harness mods tutorial.