Tycho is a local-first control center for supervising coding-agent sessions across projects. It gives a solo developer or technical lead one place to start agents, answer follow-up questions, inspect logs and results, and run recurring work. Use it in the terminal or through its optional Remote UI.
Tycho currently supports Codex, Claude, OpenCode, Pi, and custom profiles for
any of those native harness families. It keeps each agent's conversation,
status, and artifacts under your local ~/.tycho directory.
Tycho is early, single-operator software. Homebrew installs target macOS; source installs also work in Linux-style environments and Windows 11 through WSL when Ruby and the selected agent CLIs are available.
Homebrew is the primary install path:
brew tap firewalker06/tycho
brew install tycho
tychoTo run from source, install Ruby 3.2+, Bundler, Go, and native build tools, then run:
git clone https://github.com/firewalker06/tycho.git tycho
cd tycho
bin/setup
bin/tychobin/setup --check reports missing requirements without changing files. See
setup requirements for dependency profiles,
optional integrations, and environment overrides.
Tycho stores project definitions in ~/.tycho/config/hq.yml. A minimal project
looks like this:
projects:
- key: my-workspace
name: My Workspace
group: Personal
path: /Users/you/Code/my-workspace
agent: codexYou can also create projects from the TUI or the command line:
tycho project my-workspace --path ~/Code/my-workspace --harness codexThe complete annotated configuration is in
config/hq.yml.example. Schedules, prompt templates,
hooks, and response style use separate files under ~/.tycho/config.
For compatible local wrappers and gateways, see custom harness
profiles.
Tycho launches agent CLIs with access to the selected project. Review project
paths, prompts, and sandbox settings before starting an agent. Pi has
no native sandbox equivalent.
Do not commit your Tycho config, .env, logs, transcripts, or generated agent
artifacts; they may contain local paths, source context, or credentials. See
the security policy.
Open the TUI:
tychoRestart the terminal UI with tycho restart.
For a Homebrew installation, tycho update upgrades Tycho and restarts any
running local Remote server and scheduler daemon with the stable launcher. It
reports a no-op when either service is absent; source checkouts update through
Git instead.
To run your first agent:
- Press
2and select the project withj/k. - Press
n, enter a name and prompt, then choose Create and Run Agent. - Continue in the open chat. Type a follow-up and press Enter; reopen the chat
later with
cor Enter on the selected agent.
Start the browser-based Remote UI:
tycho serveWithout TYCHO_REMOTE_TOKEN, the Remote UI and API are safe only on localhost.
Set a token before binding to Tailscale or any other non-loopback address:
TYCHO_REMOTE_TOKEN="$(ruby -rsecurerandom -e 'puts SecureRandom.hex(24)')" \
tycho serveSee Remote Sessions for binding, Tailscale, daemon, multiserver, authentication, and API details.
Run scheduled agents:
tycho schedule list
tycho schedule daemonSee Scheduled Runs for schedule configuration and
runtime policies. Run tycho --help for the full command list.
Source-checkout users can replace tycho with bin/tycho in these examples.
- Setup requirements — dependencies, setup profiles, paths, and environment overrides.
- Custom harness profiles — compatible Codex, Claude, OpenCode, and Pi wrapper configuration.
- Remote Sessions — Remote UI, API, authentication, Tailscale, and multiserver operation.
- Scheduled Runs — recurring agent configuration and policies.
- Agent memory and delegation — session persistence and managed-agent ownership.
- Hooks, skills, and usage metrics — optional operator workflows.
- Pull request diffs use an authenticated local
ghCLI and provide read-only, agent-scoped snapshots. - Gotchas — known operational pitfalls.
- Project status — roadmap and architectural decisions.
See CONTRIBUTING.md. Run bin/test before opening a pull
request.
Tycho is released under the MIT License.