ziro 0.3.0

A terminal coding and research agent with persistent memory, RAG, progressive tool loading, subagents, MCP support, a skills library, configurable guardrails, and automatic context compaction. Runs on OpenRouter, Anthropic, OpenAI, or any OpenAI/Anthropic-compatible endpoint you point it at.

Two runtime modes, no config switch: SQLite + FAISS for local dev, PostgreSQL + pgvector when DATABASE_URL is set.

Install

The install script needs only Python 3.11.9+ and creates an isolated environment. No pipx, no uv, no admin rights.

# macOS / Linux
curl -fsSL https://ziro-agent.com/install.sh | bash

# Windows
iwr -useb https://ziro-agent.com/install.ps1 | iex

Both take --version <v>, --uninstall, and --help. Already have a Python environment you like? pip install ziro works too.

First run

ziro

With no arguments, ziro walks you through setup in the TUI: an API-key wizard (get one at openrouter.ai/keys), then optional model / theme / advanced sections, then user, thread, and agent pickers, then straight into chat. Re-run it any time with ziro setup.

ziro --user alice                          # skip the user picker
ziro --user alice --agent researcher       # pick an agent up front
ziro --user alice --flavour engineering    # scope to a workspace flavour
ziro --user alice --thread alice_abc12345  # resume a past conversation
ziro --user alice -p "summarize ./notes"   # headless: one turn, print, exit
ziro --user alice -p "..." --json          # headless, machine-readable

User ids are 1-64 characters of [A-Za-z0-9_-].

Features

Agents and workspaces

• Multi-agent: run as one of several named agents, each with its own persona, model, provider, tools, MCP servers, guardrails, permissions, and compaction policy. Per-agent on/off flags.
• Flavours: a workspace container chosen once at launch (chat, engineering, research, safe) that scopes which agents and threads you see, shares one memory across the team, and layers a policy overlay plus a dominant persona on top of its members.
• Subagents: delegate a self-contained subtask to a child agent in isolated context. Each is a single-file *.agent.md definition (persona plus scoped tools and skills) whose permissions are intersected with the parent's, never widened. Eight ship built in, including scout, solver, reviewer, tester, and fact_checker. Children can run in the background and report back unprompted when they finish.
• Execution modes: switch an agent live between normal, plan (read-only, with an explicit approval gate before anything runs), ask (confirm each write or command), and auto. Modes overlay the permission layer, so they compose with whatever policy the agent already has.

Memory and context

• Long-term memory for user-scoped and agent-scoped facts, persisted across sessions, plus per-project memory keyed to the workspace.
• Thread resumption: pick up any prior conversation by id, with AI-generated thread titles.
• Context compaction: older turns fold into a running summary as a request nears the model's window; recent turns stay verbatim. YAML-driven and model-aware, so the budget math tracks the actual context length.
• RAG: semantic search over indexed documents (.txt, .pdf, .md, directories).
• Skills library: index SKILL.md files; the agent retrieves relevant skills and loads their reference files on demand.

Tools

• Progressive tool loading: tools are deferred by default. The LLM discovers and activates only what it needs via search_tools / load_tools, so a large registry costs no context until it is used.
• Filesystem: read_file, grep, and glob_files as always-on core tools, plus ask-gated write_file / edit_file. Pure stdlib, identical on Windows and POSIX, confined to the project root.
• Shell: an optional run_shell that runs real commands on the host or in a Docker sandbox, with a cross-platform bash mode so pipes, quoting, and heredocs behave the same everywhere. Background execution is supported, and durable background shells survive a restart.
• Web: SSRF-guarded web_fetch(url) and a web_search backed by DuckDuckGo (keyless) or your own SearXNG.
• MCP: connect external MCP servers over stdio, SSE, streamable HTTP, or WebSocket, with OAuth. Persistent sessions cut per-call latency and a failing server never takes the rest down.
• Plugins: install Claude Code plugins from a git URL, a local path, or a marketplace, and use their skills, agents, prompt-macro commands, MCP servers, and hooks. Third-party code is trust-gated: shell hooks and stdio-MCP subprocesses stay inert until you consent, and editing any file revokes trust. Reads the native ~/.claude/plugins layout, so nothing needs re-authoring.

Safety

• Tool permissions: per-agent allow / deny / ask policy over tool and namespace globs. An ask triggers human-in-the-loop approval with allow-once, allow-thread, or allow-always memory. shell:* ships dangerous-default-deny.
• Guardrails: configurable input and output guards (regex injection, ML classifier, PII via Presidio, Llama Guard content safety), all YAML-driven.
• Hooks: declarative lifecycle interception across ten events, with Python or shell callables and glob matchers. Powers permission gating, shell audit, and loop detection.
• Containment for autonomous agents: agents that hold shell and write access do not hold web tools, cannot write to the control plane (secrets, policy files, .git), and run behind always-on egress and loop guards.

Interface

• Interactive TUI: transcript with live token streaming, a todo and active-tools side pane, a context-usage meter, an MCP control panel, approval and question modals, and four themes. Paints in about 1.6 seconds and is usable while the engine builds on a background thread; anything you type early is queued and runs in order.
• Slash commands dispatched before the LLM, so they cost no model call and do not pollute the transcript.
• Human handoff and clarifying questions: the agent can pause a turn for a human operator, or ask 1-4 structured multiple-choice questions and fold the answers back in.
• Local voice: optional push-to-talk speech I/O with faster-whisper STT and Piper TTS, fully on-device, no cloud key required.
• Headless and queued: single-turn -p output (text or JSON), plus a background worker pool that survives restart.
• Observability: Langfuse and LangSmith tracing, both optional.

Environment variables

Model tiers are also supported: set <PROVIDER>_PLANNING_MODEL, <PROVIDER>_EXECUTION_MODEL, or <PROVIDER>_FAST_EXECUTION_MODEL and reference them as ${EXECUTION_MODEL} in any agent's model: field.

Slash commands

Typed into a running session and dispatched before the LLM.

Managing agents and plugins

ziro plugin install https://github.com/owner/some-plugin.git   # or a local path
ziro plugin marketplace add acme https://github.com/acme/marketplace.git
ziro plugin install acme:some-plugin
ziro plugin list

python -m app.cli.manage_agents list
python -m app.cli.manage_agents add my-agent --name "My Agent"
python -m app.cli.manage_agents set-model my-agent anthropic/claude-sonnet-4-5
python -m app.cli.manage_agents add-subagent my-scout --namespaces rag --skills deep-research

Agents resolve their config most-specific-first across three roots: <project>/.ziro/agents/<id>/ → ~/.ziro/agents/<id>/ → the bundled package. So you can override or add agents for an installed ziro without touching the package: drop files under ~/.ziro/agents/<id>/.

Documentation

• Full docs: docs.ziro-agent.com
• Architecture, subsystem internals, and development setup: CONTRIBUTING.md
• Source and issues: github.com/hRupanjan/ziro

License

MIT. See LICENSE.