TaskHandoff User Guide
TaskHandoff centrally manages AI workspaces, instances, sessions, and automation across local and remote nodes.
Primary AI agents
TaskHandoff currently focuses on Codex and OpenCode. Both use the unified interface for creating, supervising, and recovering AI work. See Codex and OpenCode.
Sessions default to TaskHandoff's distinctive Compact mode, which focuses on the current task turn and greatly reduces interference from full message history. Conversation mode remains available whenever the complete chronology is needed.
Start Here
For a first-time setup:
- Learn the core concepts.
- Install TaskHandoff and sign in.
- Connect a node and configure a model.
- Configure Codex or OpenCode.
- Create your first instance.
- Start an AI session.
Audience
This guide is for TaskHandoff administrators and regular users. Steps that require administrator access are identified explicitly.
Guide Chapters
Get Started
- About TaskHandoff: purpose, core concepts, and system layout.
- Install the thctl Skill: install the usage guide into Codex, OpenCode, and similar agents so they can drive the Control Plane directly.
- Install and Sign In: server deployment, administrator setup, desktop behavior, and languages.
- First-time Setup: nodes, runtime environments, model providers, and projects.
- Interface and Workbench: navigation, boards, sidebar, and dedicated windows.
Instances and AI
- Codex and OpenCode: primary agents, model protocols, and selection guidance.
- Create and Manage Instances: workspaces, runtimes, status, templates, and deletion.
- Instance Settings: AI defaults, agent settings, models, apps, and Git access.
- Use AI Sessions: session creation, permissions, messages, progress, and session management.
- Repository Workflows: files, changes, worktrees, branches, and remote delivery.
- Apps and Terminal: managed apps, terminal access, and browser previews.
Organization and Administration
- Stories and Automation: documents, preset actions, schedules, and triggers.
- Node management, resource management, and users and access.
- Desktop, Mobile, chat bridges, and remote access.
- Settings and Security: global settings entry points and security principles.
- Troubleshooting: common node, instance, session, and repository problems.
Operations and Reference
- Updates and Versions: release sets for Control Plane, Node Agent, and instances.
- Data, Backup, and Recovery: backup strategy for configuration, instance data, and workspaces.
- Status and Glossary: UI states, error messages, and terminology.
- Client Capability Matrix: capability differences across web, desktop, mobile, and chat.
- Private Repository Tutorial and Worktree Tutorial: end-to-end workflow examples.
- FAQ: short answers to common questions.
Read by Role
| Role | Recommended chapters |
|---|---|
| Regular user | Instances, AI sessions, repository workflows, apps and terminal |
| Administrator | Install, first-time setup, settings and security, troubleshooting |
| Automation user | AI sessions, Stories and automation, settings and security |