Metadata-Version: 2.4
Name: holoctl
Version: 0.5.1
Summary: Universal project operating system for AI coding assistants
Author: Felipe Carillo
License: MIT License
        
        Copyright (c) 2026 Felipe Carillo
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/FelipeCarillo/holoctl
Project-URL: Repository, https://github.com/FelipeCarillo/holoctl
Keywords: ai,project-management,kanban,claude-code,cursor,windsurf,copilot,aider,agents,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn>=0.30
Dynamic: license-file

# holoctl

> Universal project operating system for AI coding assistants.

<p>
  <a href="./README.md"><img src="https://img.shields.io/badge/lang-English-blue?style=flat-square" alt="English"/></a>
  <a href="./README.pt-br.md"><img src="https://img.shields.io/badge/lang-Português-green?style=flat-square" alt="Português"/></a>
</p>

[![PyPI version](https://img.shields.io/pypi/v/holoctl.svg)](https://pypi.org/project/holoctl/)
[![PyPI downloads](https://img.shields.io/pypi/dm/holoctl.svg)](https://pypi.org/project/holoctl/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-%3E%3D3.11-brightgreen.svg)](https://www.python.org)

---

## 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):

```bash
uv tool install holoctl
```

Or with pip:

```bash
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

```bash
# 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.

```bash
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.

```bash
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

```bash
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

```markdown
---
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

```json
{
  "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](https://github.com/FelipeCarillo)
