Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 1 addition & 22 deletions .claude/skills/tycho/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,15 @@
---
name: tycho
description: Manages Tycho-monitored projects and managed agents. Use when the user asks to deploy, check status, manage maintenance mode, create/list/run/stop/send/archive/clone agents, or control schedules for any project.
description: Manages Tycho-monitored projects and managed agents. Use when the user asks to check status, create/list/run/stop/send/archive/clone agents, or control schedules for any project.
---

# Tycho CLI Skill

Manage Kamal-deployed projects, managed agents, and scheduled runs via the `tycho` CLI.

## Quick Reference

| Group | Command | Description |
|-------|---------|-------------|
| **app** | `app list` | List projects with Kamal deployment |
| | `app status <project-key>` | Check a project's health and last action |
| | `app deploy <project-key>` | Start a deploy |
| | `app maintenance <project-key>` | Enable maintenance mode |
| | `app live <project-key>` | Resume live traffic |
| **project** | `project update <project-key> --pr-url <url>` | Set / clear open PR URL |
| **agent** | `agent create <project-key> <prompt>` | Create (and optionally run) a managed agent |
| | `agent list [<project-key>]` | List agents, optionally filtered by project |
Expand Down Expand Up @@ -161,20 +155,6 @@ tycho agent clone my-project-agent-3 --run # clone and start immediately

---

## `tycho app` — Deployment Commands

```bash
tycho app list
tycho app status my-project
tycho app deploy my-project
tycho app maintenance my-project
tycho app live my-project
```

Actions run as detached background processes. Check progress via `app status` or the TUI.

---

## `tycho schedule` — Schedule Management

```bash
Expand All @@ -200,7 +180,6 @@ tycho project update my-project --pr-url "" # clear
## Project Keys

```bash
tycho app list # Kamal-enabled projects
grep "^- key:" ~/.tycho/config/hq.yml # all projects (including agent-only)
```

Expand Down
1 change: 0 additions & 1 deletion .github/ISSUE_TEMPLATE/feature_request.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,4 @@ assignees: ""

## Notes

Mention affected areas such as TUI, Remote UI, Kamal actions, managed agents,
hooks, config, or docs.
12 changes: 4 additions & 8 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,10 @@

`bin/tycho` is the executable and boots through `HQ::CLI` in `lib/hq/cli.rb`. Keep the main Bubbletea model and screen-level update flow in `lib/hq/app.rb`, config loading in `lib/hq/registry.rb`, terminal input shims in `lib/hq/bubbletea_input.rb`, domain and process-management logic under `lib/hq/domain/`, form/composer components under `lib/hq/ui/components/`, and rendering split between the aggregator in `lib/hq/ui/rendering.rb` and focused modules under `lib/hq/ui/rendering/`.

Domain files are intentionally small: `constants.rb` owns log/schema paths, `version_lookup.rb` handles RubyGems lookups, `kamal_action.rb` manages detached Kamal commands, `app_project.rb` handles project metadata and health checks, `managed_agent.rb` manages Codex/Claude-compatible execution and structured results, and `agent_store.rb` persists managed agents.

Project definitions live in `~/.tycho/config/hq.yml`, system prompt templates live in `~/.tycho/config/system_prompts.yml`, and structured managed-agent output is described by `~/.tycho/config/schemas/agent_result.json`. Project status, key decisions, and roadmap live in `docs/PROJECT_STATUS.md`; update it when durable priorities, milestones, or architectural decisions change. Research and workflow notes live under `docs/`, including `docs/GOTCHAS.md`, `docs/REMOTE_SERVER.md`, `docs/research/charm-ruby.md`, `docs/research/codex-json-schema-research.md`, and `docs/research/claude-json-schema-research.md`.

Runtime artifacts are written to `~/.tycho/logs/`, including app state files such as `actions.json` and `managed_agents.json`, application logs in `hq.log`, project logs under `~/.tycho/logs/projects/{project}/`, archived project logs under `~/.tycho/logs/projects/archived/`, and per-agent logs/status/result files under `~/.tycho/logs/agents/`. Keep automated checks under `test/`; the existing rendering regression coverage lives in `test/rendering_test.rb`.
Runtime artifacts are written to `~/.tycho/logs/`, including app state files such as `managed_agents.json`, application logs in `hq.log`, project logs under `~/.tycho/logs/projects/{project}/`, archived project logs under `~/.tycho/logs/projects/archived/`, and per-agent logs/status/result files under `~/.tycho/logs/agents/`. Keep automated checks under `test/`; the existing rendering regression coverage lives in `test/rendering_test.rb`.

## Build, Test, and Development Commands

Expand Down Expand Up @@ -37,19 +36,16 @@ If you introduce new tooling, document the command here and keep it runnable fro

Follow the existing Ruby style across `bin/tycho` and `lib/hq/**/*.rb`: two-space indentation, snake_case for methods and variables, SCREAMING_SNAKE_CASE for constants, and short guard clauses where they simplify flow. Keep classes and modules focused, and prefer small helper methods over deeply nested conditionals.

Preserve the current separation of concerns: registry/config parsing stays out of the TUI layer, managed-agent and Kamal behavior belongs in domain objects, and screen/layout code should stay in the UI modules.

Preserve the current file-level conventions: `# frozen_string_literal: true`, double-quoted strings, and concise comments only where the code is not obvious.

The repo ships a `.rubocop.yml` that pins double-quoted string style and Ruby 3.4. `bundle exec rubocop` is not part of the bundle; if you run RuboCop locally, use the available executable and keep changes scoped to the requested files.

## Runtime Behavior & External Integrations

Health checks run concurrently via Ruby threads. `AppProject#check_health!` uses HEAD requests against the configured healthcheck path and root URL; keep HEAD semantics because kamal-proxy maintenance detection depends on them. A root URL 503 means the app is in maintenance mode even if the health endpoint looks healthy.

Kamal actions run as detached background processes through `mise exec`, using `TYCHO_MISE_BIN` first, then common local install paths, then `mise` on `PATH`. Prefer a project's `bin/kamal` binstub and fall back to `bundle exec kamal`. Logs go to `~/.tycho/logs/projects/{project}/action.log`, action state is persisted to `~/.tycho/logs/actions.json`, and actions are restored and checked for liveness on startup. Archiving a project moves its config entry from `~/.tycho/config/hq.yml` to `~/.tycho/config/hq.archived.yml`, moves `~/.tycho/logs/projects/{project}/` to `~/.tycho/logs/projects/archived/YYYY-MM-DD_project-name/`, and archives related managed-agent logs.

The app auto-refreshes every 30 seconds. Action and agent status is polled every 10 seconds. Multiple projects can have concurrent actions running, and completed actions trigger a health refresh.
The app auto-refreshes every 30 seconds. Agent status is polled every 10 seconds.

Managed agents are configured from project settings in `~/.tycho/config/hq.yml`, with prompt templates loaded from `~/.tycho/config/system_prompts.yml`. Codex agents use JSON output and `~/.tycho/config/schemas/agent_result.json`; Claude and custom Claude-compatible harnesses use `--output-format stream-json` so logs stream incrementally. Use `TYCHO_CODEX_BIN` and `TYCHO_CLAUDE_BIN` to override built-in agent executables. Custom Claude-compatible wrappers belong in `custom_harnesses` with `adapter: claude` and an `execution_command`; provider-specific details should live in that wrapper or command configuration, not in HQ. Native Claude/Codex `session_id` values are persisted on managed agents and reused with `--resume` after the first run; HQ still treats `memory.jsonl` as the canonical transcript and only replays the bounded memory prompt when no native session is known. Preserve structured inquiry submission and focus-aware chat behavior when changing agent flows.

Expand All @@ -71,7 +67,7 @@ For input components, keep paste handling compatible with Bubbles `TextInput` an

This repository now has lightweight automated coverage under `test/`. Every change should at minimum pass `bin/test` and a manual run of `bin/tycho` when TUI behavior is affected.

Validate the affected key paths in the UI, especially grouped project rows, table alignment, detail views, sidebar log inspection, agent create/edit flows, agent chat and structured inquiry submission, refresh, deploy, maintenance toggle, and the `g` shortcut that opens the selected project in a terminal.
Validate the affected key paths in the UI, especially grouped project rows, table alignment, detail views, sidebar log inspection, agent create/edit flows, agent chat and structured inquiry submission, refresh, and the `g` shortcut that opens the selected project in a terminal.

For Remote UI `/ui` changes, run `bundle exec ruby test/remote_server_test.rb` and do browser verification for user-visible behavior. A safe fallback pattern is to start `bin/tycho serve` on a spare localhost port with temp env vars (`TYCHO_CONFIG_PATH`, `TYCHO_SYSTEM_PROMPTS_PATH`, `TYCHO_LOGS_ROOT`), create fixture data through the JSON API, then drive `http://127.0.0.1:{port}/ui` with Playwright + local Google Chrome. Check concrete browser facts such as focused form values surviving `refresh({ force: true })`, details toggles preserving state across polling, mutually exclusive panels closing as expected, and sticky/fixed docks staying pinned inside the viewport.

Expand All @@ -83,6 +79,6 @@ When adding tests, keep using simple Ruby test files under `test/` with `*_test.

Recent commits use short, imperative subjects such as `Fix table column alignment across screens` and `Add custom Claude harness support`. Keep commit messages in that style and scope each commit to one logical change.

Pull requests should include a brief summary, manual verification steps, and screenshots or terminal captures for visible TUI changes. Link related issues when applicable and note any changes to `~/.tycho/config/hq.yml`, `~/.tycho/config/system_prompts.yml`, structured agent schemas, hardcoded project paths, logs, or external dependencies such as `mise`, RubyGems API access, Codex, Claude, or Bedrock-backed Claude execution.
Pull requests should include a brief summary, manual verification steps, and screenshots or terminal captures for visible TUI changes. Link related issues when applicable and note any changes to `~/.tycho/config/hq.yml`, `~/.tycho/config/system_prompts.yml`, structured agent schemas, hardcoded project paths, logs, or external dependencies such as Codex, Claude, or Bedrock-backed Claude execution.

Also call out changes to Bubbletea input handling, bracketed paste behavior, or Bubbles text components because they affect chat, inquiry, and agent editor typing flows.
5 changes: 1 addition & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,7 @@ All notable changes to Tycho will be documented in this file.
### Notable Releases

- Add persisted Remote UI server switching for configured `remote_servers`,
including backend proxy routes, selected-server persistence, and peer health
display. (#39)
including backend proxy routes and selected-server persistence. (#39)
- Add Remote UI skill autocomplete and a quick agent switcher for faster chat
composition and agent navigation. (#38)
- Show run summaries in Remote UI conversations and allow any Remote UI
Expand Down Expand Up @@ -87,8 +86,6 @@ All notable changes to Tycho will be documented in this file.
- Improve the Remote UI Summary surface and keep run summary blocks out of the
main conversation stream. (#11)

- Fix Remote readiness checks by sharing executable resolution for `mise`,
Kamal, Codex, Claude, and compatible harnesses. (#12)
- Fix Claude structured output schema handling so Claude-compatible runs can
produce and parse structured results reliably. (#13)
- Resume stopped schedules safely after interactive scheduled agents are
Expand Down
Loading
Loading