shai-tix 0.1.1

File-based task management for AI agents with human-editable markdown storage.

---

Welcome to shai_tix Documentation

File-based task management for AI agents with human-editable markdown storage.

What is shai_tix?

shai_tix is a task management system designed primarily for AI agents (like Claude Code) while remaining fully accessible to humans. It uses plain files and directories as storage, so both AI and humans can read, edit, and track changes through git.

Design Philosophy

AI-First, Human-Friendly

• For AI: CLI interface (shai-tix) with simple text output that AI can parse

• For Humans: Markdown files you can browse, edit, and version control

Dual Storage Architecture

• Filesystem (Source of Truth): Human-readable directories and markdown files

• SQLite Index (Cache): Fast queries without scanning directories

Simple Two-Level Hierarchy

Story (Feature or Epic)
└── Task (Atomic work unit)

No deep nesting. If a task needs subtasks, promote it to a story.

Quick Start

For AI Agents (CLI):

# Create a story and tasks
shai-tix create_story "User Authentication" --description "Implement login/logout"
shai-tix create_task 1 "Create login form"
shai-tix create_task 1 "Add session management"

# Query and update
shai-tix list_stories
shai-tix update_task 2 --status COMPLETED

For Humans (File System):

.tix/
└── stories/
    └── story-2025-01-15-00001-user-authentication/
        ├── metadata.json          # {"status": "IN_PROGRESS"}
        ├── description.md         # Editable markdown
        └── tasks/
            └── task-2025-01-15-00002-create-login-form/
                ├── metadata.json
                └── description.md

Install

shai_tix is released on PyPI, so all you need is to:

$ pip install shai-tix

To upgrade to latest version:

$ pip install --upgrade shai-tix