Theway

theway is a terminal-first AI coding agent for local developer workflows. It reads and edits files, runs shell commands, keeps resumable SQLite-backed sessions, and works with multiple model providers, including local OpenAI-compatible servers.

The client (theway) and the daemon (thewayd) are separate processes. The daemon owns the agent runtime, tools, sessions, skills, and automation; the TUI is a pure client that spawns or reuses a daemon.

Install and use

Run from source

git clone https://github.com/ptlzc/theway.git
cd theway
cargo build --release

The CLI binary is at ./target/release/theway.

Install from Cargo

cargo install --locked theway-tui theway-daemon

This installs the theway and thewayd binaries from crates.io into ~/.cargo/bin.

Quick install / update with curl

curl -fsSL https://raw.githubusercontent.com/ptlzc/theway/main/scripts/install-release.sh | bash

This downloads the latest prebuilt theway, thewayd, and tgrep release binaries from GitHub for your OS/architecture and atomically replaces the installed copies in ~/.cargo/bin (plus the tw shorthand). It is much faster than cargo install because it never compiles anything.

The script detects Linux/macOS/Windows (x86_64 / aarch64), verifies the downloaded files against the release SHA256SUMS, and leaves a running thewayd alone by default. Linux binaries are built on Ubuntu 22.04, so they require glibc 2.35 or newer. If the installed binary reports GLIBC_… not found, do not try to replace the system glibc; build from source instead with ./scripts/install.sh so the binary links against your local libc.

# Restart the old thewayd after install (other terminal sessions will disconnect)
curl -fsSL https://raw.githubusercontent.com/ptlzc/theway/main/scripts/install-release.sh | bash -s -- --restart-daemon

# Pin a release / choose the install directory
curl -fsSL https://raw.githubusercontent.com/ptlzc/theway/main/scripts/install-release.sh | bash -s -- --tag v0.1.22 --bin-dir ~/.local/bin

If you prefer to inspect the script before running it, download it first:

curl -fsSL https://raw.githubusercontent.com/ptlzc/theway/main/scripts/install-release.sh -o install-release.sh
bash install-release.sh

From a repository checkout, make install-release runs the same script.

The npm package @theway-ai/sdk is a TypeScript SDK for talking to thewayd; it is not the CLI.

Install locally

./scripts/install.sh

This installs theway, thewayd, and the tw shorthand into ~/.cargo/bin.

Start

theway                  # open the TUI in the current project
theway --resume         # pick a previous session
theway --thinking high
theway --provider anthropic --model claude-haiku-4-5

On first use, /model opens the model picker. /model <provider:model-id> switches directly and saves the selection as the next startup default. Set an API key with export <PROVIDER>_API_KEY=... or /login <provider> <key>.

Inside the REPL, /help lists every slash command. The most-used ones are /model, /thinking, /sessions, /compact, /triggers, /cron, and /quit. See docs/startup-modes.md for daemon lifecycle and spawn modes.

What it can do

• Read, write, edit, and search files; run shell commands
• Keep per-project resumable sessions and cross-session memory
• Attach images to the first prompt with --image
• Load skills and provision MCP servers from ~/.theway/config.toml
• Delegate work to subagents and orchestrate DAGs
• Create session-scoped triggers and cron jobs, including stateful loops with a triage inbox
• Run command hooks and HTTP webhooks on lifecycle events
• Work with OpenAI-compatible local model servers; see docs/ds4.md

Documentation

• GitHub Wiki — tutorials, FAQ, recipes, and runbooks
• Architecture — crate layout, tool policy, daemon path context, storage
• Startup modes — daemon spawn/reuse and controller lifecycle
• Loops — stateful cron jobs and the triage inbox
• DS4 — KV prefix-cache optimizations for local models
• Hooks — local command hooks and HTTP webhooks
• Extensions — runtime extension authoring
• Graph engineering mode — subagent and DAG orchestration
• Testing and Rust test files — test layout and standards

Community and support

• Report bugs or request features through GitHub Issues.
• Discuss ideas in GitHub Discussions.

Development

cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --check

The Makefile wraps the same CI pipeline; make ci runs it locally.

License

MIT