Unio

cargo run -p unio -- exec "inspect README.md"
cargo run -p unio -- tool read --args path=README.md

Start Here

• Install: requirements, releases, and source builds.
• Quickstart: first commands to run locally.
• CLI: command surface and examples.
• Tools And Approvals: direct tools and safety modes.
• Skills: skill discovery and invocation.
• Architecture: workspace layout and runtime flow.

Install

Requirements

• Rust stable toolchain
• Cargo
• Windows, macOS, or Linux

Check the local toolchain:

rustc --version
cargo --version

Releases

Pre-built archives are published from version tags.

Each archive contains:

• unio: user-facing CLI.
• unio-daemon: local runtime process.

See the project releases at https://github.com/way2ai/unio/releases.

Build From Source

git clone https://github.com/way2ai/unio.git
cd unio
cargo build --workspace --release

Compiled binaries are written to target/release/.

Run From Source

During development, run commands through Cargo:

cargo run -p unio -- status
cargo run -p unio -- exec "hello unio"

Quickstart

Run all commands from the repository root.

Verify The Workspace

cargo fmt --all
cargo test --workspace
cargo build --workspace

Check Status

cargo run -p unio -- status

Run A Prompt

cargo run -p unio -- exec "hello unio"

If model credentials are not configured, Unio uses the mock provider so local development remains deterministic.

Configure A Real Model

Unio reads persistent model settings from ~/.unio/config.toml. Environment variables override the file for temporary changes.

Use the slash command to create or update the file:

cargo run -p unio -- "/model"

[model]
provider = "openai-compatible"
model = "gpt-4o-mini"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."

For Anthropic:

[model]
provider = "anthropic"
model = "claude-3-5-sonnet-latest"
api_key = "sk-ant-..."

Supported providers are openai, openai-compatible, anthropic, and mock. If a real provider is selected without an API key, Unio reports the requested provider but falls back to the mock provider.

Read A File Through The Tool Layer

cargo run -p unio -- tool read --args path=README.md

Inspect Recent Work

cargo run -p unio -- resume --limit 10
cargo run -p unio -- trace <trace_id> --run <run_id>

Next Steps

• Use CLI for the command reference.
• Use Tools And Approvals before enabling write or process execution.
• Use Skills to add repository-specific workflows.

CLI

The unio binary is the user-facing entry point. It talks to the daemon and keeps command behavior scriptable for terminals, editors, and automation.

Common Commands

cargo run -p unio -- status
cargo run -p unio -- exec "summarize this repository"
cargo run -p unio -- resume --limit 10
cargo run -p unio -- trace <trace_id> --run <run_id>

Interactive Entry

Run without a subcommand to open the terminal surface:

cargo run -p unio

Useful prompt features:

• / opens command suggestions.
• @ searches workspace files.
• Shift+Enter or Ctrl+J inserts a newline.
• Ctrl+C twice exits.

Model Configuration

The /model slash command shows and updates the persistent model settings in ~/.unio/config.toml.

cargo run -p unio -- "/model"

/model shows the active provider, then prompts for provider, model, base URL, and API key in either the terminal surface or a direct slash invocation. The flow updates ~/.unio/config.toml; environment variables still override the file.

Run Rendering

Interactive and direct command output renders model and tool activity as readable run summaries. Tool events are grouped by purpose instead of exposing raw event names:

• Running: model execution and stage changes.
• Tool: completed tool calls with the tool name and concise target.
• Approval: tool calls waiting for approval or approval decisions.
• Skill: skill-tool activity with the skill name when available.
• Done: final stage, model, token usage, and context ratio.

Raw trace event names remain available through /trace <trace_id> for debugging.

Direct Tool Commands

cargo run -p unio -- tool read --args path=README.md
cargo run -p unio -- tool write --args path=notes.txt,content=hello

Write and process tools may require approval depending on the selected policy.

Tools And Approvals

Tools are registered capabilities that the daemon can execute after security precheck. The approval layer separates ordinary reads from operations that can change files or run processes.

Read Tool

cargo run -p unio -- tool read --args path=README.md

Write Tool

In default policy, writes require approval:

cargo run -p unio -- tool write --args path=notes.txt,content=hello

List and resolve approvals:

cargo run -p unio -- approvals
cargo run -p unio -- approvals approve approval_xxx
cargo run -p unio -- approvals deny approval_xxx

Full Trust Mode

Use full-trust only when you intentionally allow the requested operation:

cargo run -p unio -- tool write --approval full-trust --args path=notes.txt,content=hello

Policy Contract

• allow: the tool can run immediately.
• deny: the tool is blocked.
• approval-required: the tool waits for an explicit user decision.

Tool implementations should stay small and delegate risk decisions to crates/security.

Skills

Skills let a repository or user define reusable workflows in Markdown. Unio discovers skills from workspace and user directories.

Discovery Paths

{workspace}/.unio/skills/
~/.unio/skills/

Create A Workspace Skill

New-Item -ItemType Directory -Force .unio\skills\repo-helper
Set-Content .unio\skills\repo-helper\SKILL.md "# Repo helper`nUse for repository analysis."

List discovered skills:

cargo run -p unio -- skills

Invoke A Skill

cargo run -p unio -- tool skill-tool --approval full-trust --args name=repo-helper,request=inspect-modules

Skill Contract

• A skill lives in a directory with a SKILL.md file.
• The first paragraph should state when the skill applies.
• Extra scripts or assets should stay inside the skill directory.
• Skill execution uses the same tool and approval path as other operations.

Architecture

Unio is a Rust workspace organized around a local daemon. The CLI is thin: it collects user input and sends work to the daemon. The daemon owns state, session and run lifecycle, approvals, tool execution, storage, and trace events.

Workspace Layout

apps/
  cli/       user-facing unio command
  daemon/    local runtime for sessions, runs, tools, storage, and trace

crates/
  core/           IDs, paths, metadata, shared utilities
  protocol/       CLI, daemon, and agent protocol types
  agent/          root agent, planner, sub-agent, and skill-agent contracts
  model/          model provider abstraction and mock provider
  tools/          tool registry and execution contract
  security/       approval policy and risk precheck
  skills/         skill discovery and skill-tool execution
  storage/        SQLite metadata and JSONL transcript stores
  observability/  trace and context events

Runtime Flow

user
  -> unio CLI
  -> daemon
  -> agent
  -> model provider or tool
  -> security approval when needed
  -> storage and trace records
  -> user-visible result

Current Contracts

• apps/cli owns user interaction and command parsing.
• apps/daemon owns runtime orchestration and persistence.
• crates/protocol defines shared request and response types.
• crates/security returns allow, deny, or approval-required decisions.
• crates/tools executes registered tools only after precheck.
• crates/storage persists metadata, transcripts, and trace data.
• crates/observability records structured runtime events.

Design Principles

• Keep model calls, tool execution, and persistence out of the CLI.
• Route every risky operation through the security policy.
• Resolve model configuration in the model crate from ~/.unio/config.toml, with environment variables as higher-precedence overrides.
• Make local development possible with the mock provider.
• Prefer explicit IDs for sessions, runs, agents, and traces.

Development

Commands

Run from the repository root:

cargo fmt --all
cargo test --workspace
cargo build --workspace

Run the CLI:

cargo run -p unio -- status
cargo run -p unio -- exec "hello"

Run a direct tool command:

cargo run -p unio -- tool read --args path=README.md

Repository Guidelines

• Keep documentation and implementation synchronized.
• Update CHANGE.md for meaningful behavior, architecture, workflow, or documentation changes.
• Update README.md when setup, usage, or user-facing behavior changes.
• Add or update docs under docs/ when architecture, protocol, security, storage, tools, or agent behavior changes.

Tests

Tests live beside implementation in each crate under #[cfg(test)]. Prefer focused unit coverage near the code that owns the behavior.

Release

Release artifacts are built by .github/workflows/release.yml when a tag that matches v* is pushed.

Targets

The release workflow builds both unio and unio-daemon, packages them, and attaches the archives to a GitHub Release.

Create A Release

git tag v0.1.0
git push origin v0.1.0

Local Release Build

cargo build -p unio -p unio-daemon --release

Site Operations

The project site is an mdBook published to GitHub Pages. English content lives under docs/src/; Simplified Chinese content lives under docs/zh/src/.

Local Preview

Install mdBook:

cargo install mdbook

Serve the English site:

mdbook serve docs

Serve the Chinese site:

mdbook serve docs/zh

Local Build

mdbook build docs
mdbook build docs/zh

English output is written to docs/book/. Chinese output is written to docs/book/zh-CN/.

GitHub Pages

The .github/workflows/deploy-site.yml workflow runs on pushes to main and on manual dispatch. It:

1. Checks out the repository.
2. Sets up Rust stable.
3. Runs cargo test --workspace.
4. Installs mdBook.
5. Builds English and Chinese mdBooks.
6. Uploads docs/book/ as the Pages artifact.
7. Deploys the artifact through GitHub Pages.

Repository Pages should use GitHub Actions as the source.