holoctl 0.5.0

Universal project operating system for AI coding assistants

holoctl

Universal project operating system for AI coding assistants.

---

What is holoctl?

holoctl is a CLI tool that turns any directory into a fully structured AI-ready project. It gives you a Kanban board, agent definitions, slash commands, and a live web dashboard — all version-controlled in .holoctl/ alongside your code.

One project root. Any number of sub-repos and directories underneath. One /holoctl slash command to set it all up inside Claude Code.

my-project/              ← project root (holoctl init here)
├── backend/             [git · Node]
├── frontend/            [git · React]
├── mobile/              [git · React Native]
├── infra/               [Terraform]
├── .holoctl/            ← all project state lives here
│   ├── config.json
│   ├── board/
│   │   └── tickets/
│   ├── agents/
│   ├── commands/
│   └── context/
└── README.md

---

Install

Recommended (handles PATH automatically):

uv tool install holoctl

Or with pip:

pip install holoctl

holoctl lives entirely inside your workspace. It writes nothing to $HOME and keeps no global registry of projects. Initialize once with holoctl init, run holoctl compile --target claude to wire up the /holoctl slash command in that workspace's .claude/commands/. Repeat per workspace.

---

Quick Start

# 1. Go to your project root
cd ~/my-project

# 2. Initialize
holoctl init

# 3. Open the dashboard
holoctl serve
# → http://127.0.0.1:4242

# 4. Compile for your AI tool(s)
holoctl compile --target claude    # CLAUDE.md + .claude/commands/
holoctl compile --target cursor    # .cursor/commands/ + .cursor/rules/
holoctl compile --target windsurf  # .windsurfrules
holoctl compile --target copilot   # .github/copilot-instructions.md
holoctl compile --target devin     # AGENTS.md + .devin/skills/

Or just type /holoctl in Claude Code — it detects, initializes, and compiles automatically.

---

Features

📋 Kanban Board

Ticket management built for AI agents. Every ticket is a Markdown file with frontmatter — readable by humans and machines.

holoctl board add '{"title":"Add auth flow","agent":"developer","projects":["backend"]}'
holoctl board add '{"title":"Wire SSE","agent":"developer","projects":["backend","frontend"]}'
holoctl board ls
holoctl board ls --project backend --status doing
holoctl board move PRJ-001 doing
holoctl board set PRJ-001 priority p0
holoctl board stat

Tickets vincúlam a um ou vários projetos descobertos no workspace via o campo projects: string[] (substituiu o antigo scope).

📁 Multi-Project Workspace

A workspace (the directory where you ran holoctl init) is auto-scanned: any direct subdirectory containing a project marker (.git, package.json, pyproject.toml, Cargo.toml, go.mod, …) appears as a project in the dashboard's Projects tab and on the board's project filter — no manual registration required.

holoctl repo list                          # see what was discovered
holoctl repo add ./infra --name infra     # optional: override / add a subdir the scan missed
holoctl repo info backend

🌐 Web Dashboard

holoctl serve              # http://127.0.0.1:4242 (localhost only)
holoctl serve --host 0.0.0.0  # expose on local network

Tab	Description
Board	Kanban view with real-time SSE updates
Repos	Git status per sub-repo: branch, last commit, remote link
Files	Full file tree with tech-stack badges
Agents	AI agent definitions
Commands	Slash commands library
Context	Project knowledge base

File tree badges: Git, Node, React, Vue, React Native, Python, Go, Rust, Flutter, Docker, Terraform, iOS, Java, PHP.

🤖 AI Tool Integration

holoctl compile translates .holoctl/ into the native format of each AI tool:

Tool	Slash Command	Context File
Claude Code	.claude/commands/*.md	CLAUDE.md
Cursor	.cursor/commands/*.md	.cursor/rules/holoctl.md
Windsurf	(n/a)	.windsurfrules
GitHub Copilot	(n/a)	.github/copilot-instructions.md
Devin CLI	.devin/skills/*/SKILL.md	AGENTS.md

🔧 No Global Setup

holoctl writes nothing to $HOME — there is no global registry of projects and no global slash-command installer. The /holoctl slash command is generated per workspace by holoctl compile --target claude, which writes .claude/commands/holoctl.md inside that workspace. Run compile once per workspace where you want the slash command available.

---

Commands

holoctl init               Initialize .holoctl/ in the current workspace
holoctl overview           One-screen workspace snapshot (board, projects, agents, suggested next)
holoctl board <cmd>        Manage tickets (add, ls, move, set, stat, get)
holoctl repo <cmd>         Inspect / override discovered subprojects
holoctl compile            Compile to tool-specific files
holoctl serve              Start the web dashboard
holoctl agent <cmd>        Manage agent definitions
holoctl doctor             Check workspace health

---

.holoctl/ Structure

.holoctl/
├── config.json          ← project settings (name, prefix, board config, repos)
├── activity.jsonl       ← append-only event log
├── board/
│   ├── index.json       ← ticket index (auto-rebuilt from .md files)
│   └── tickets/
│       └── PRJ-001-my-ticket.md
├── agents/
│   └── developer.md
├── commands/
│   └── review.md
└── context/
    ├── decisions/
    └── documents/

---

Ticket Format

---
id: PRJ-001
title: Add authentication
agent: developer
projects: backend, shared
status: doing
priority: p1
sprint: sprint-1
created: 2026-05-04
updated: 2026-05-04
completed: null
depends: null
tags: auth, security
---

# Start
(Current state before starting)

# Goal — Definition of Done
- [ ] JWT auth implemented
- [ ] Tests passing

# Context
Why this ticket exists.

---

Configuration

{
  "project": {
    "name": "My Project",
    "prefix": "MP",
    "repos": [
      { "name": "backend",  "path": "./backend",  "description": "Node API" },
      { "name": "frontend", "path": "./frontend", "description": "React app" }
    ]
  },
  "board": {
    "statuses": ["backlog", "doing", "review", "done", "cancelled"],
    "priorities": ["p0", "p1", "p2", "p3"],
    "idPadding": 3
  },
  "targets": ["claude", "cursor"]
}

---

Requirements

• Python ≥ 3.11

---

License

MIT © Felipe Carillo