Getting started

From your first prompt to a harness of your own. Install PyLattice, explore Code Mode, and make the agent work your way.

PYTHON 3.11+TERMINAL FIRSTOPEN SOURCE

TUTORIAL / HARNESS MODS

Build an agent that fits.

Write a Python factory, add a tool, and run your own harness. Start with a working offline example.

Build your first mod →

Install PyLattice

You need Python 3.11 or newer, Git, and uv. Run these commands in a terminal:

Terminal · install

git clone https://github.com/Protocol-Lattice/PyLattice.git
cd PyLattice
uv sync

The commands in these docs assume you are in the repository root. PyLattice uses the current directory as its workspace unless you pass --workspace PATH.

Run your first task

Try the offline demo

After installing dependencies, the demo runs without credentials or model requests.

Terminal · offline demo

uv run agent-tui --demo

Try “Help me understand this project.” The demo uses scripted responses to show the interface and tool flow.

Connect the live agent

Copy the environment template, then add your OPENROUTER_API_KEY to the workspace’s .env file.

Terminal · environment

cp .env.example .env

.env · add this setting

OPENROUTER_API_KEY=your_key_here

Terminal · launch

uv run agent-tui --prompt "Help me understand this project."

The executor defaults to openrouter/free; the decision model defaults to typesafe/jev-1.13. Use --model and --router-model to select other models.

Follow the work. Expand tool traces to inspect actions, respond to approval prompts, and press Esc to cancel a running program.

Choose a run mode

Common launch commands
Command	Behavior
`uv run agent-tui`	Code Mode by default: the decision model selects a Python tool program or a final answer.
`uv run agent-tui --no-code-mode`	Use the planner and Harness Router MCTS to select individual tools.
`uv run agent-tui --fast`	Use Jev routing without the planner; selects the per-tool loop.
`uv run agent-tui --read-only`	Disable mutating tools, including file writes and commands.
`uv run agent-tui --demo --no-code-mode`	Try the routed loop offline.

--routing, --route-mcts, --no-planner, and --fast select the per-tool loop. Use --fast for routing without planning; MCTS requires the planner.

Configure your workspace

Terminal · workspace and limits

uv run agent-tui --workspace /path/to/project --context-chars 64000 --max-steps 24
uv run agent-tui --help

Frequently used settings
Flag	What it controls
`--context-chars N`	Request context budget; also configurable with `AGENT_TUI_CONTEXT_CHARS`.
`--max-steps N`	Model turns per task. A Code Mode turn can contain multiple tool actions.
`--command-timeout SECONDS`	Time limit for a workspace command.
`--no-memory`	Disable persistent workspace memory.
`--skills-dir PATH`	Add a skill collection. Repeat for multiple directories.
`--extensions PATH`	Load MCP servers and command hooks from TOML.
`--mods PATH`	Select trusted Python component factories using a TOML manifest.

Explicit CLI values take precedence over supported environment settings. The CLI loads .env from the selected workspace without overwriting variables already set in your environment.

Find your way around

Commands inside the terminal app
Command	Use it to
`/help`	List interactive commands.
`/context` · `/compact`	Inspect context usage or shorten conversation history.
`/skills` · `/skill NAME`	List workflows or pin one across tasks.
`/plugins`	Inspect the plugin marketplace and installed plugins.
`/mcp` · `/hooks`	Inspect server status and middleware hooks.
`/memory`	Inspect saved workspace notes and outcomes.

Keep building

Understand Code Mode ↗

Learn the tool bridge, response shape, and how to recover from a failed program.

Connect your workspace ↗

Add skills, persistent memory, MCP servers, and middleware hooks.