Metadata-Version: 2.4
Name: sabbatical
Version: 0.2.3
Summary: Local AI agent orchestration CLI — async task collaboration for developers
License: Commons Clause License Condition v1.0
         
         The Software is provided to you by the Licensor under the License,
         as defined below, subject to the following condition.
         
         Without limiting other conditions in the License, the grant of rights
         under the License will not include, and the License does not grant to
         you, the right to Sell the Software.
         
         For purposes of the foregoing, "Sell" means practicing any or all of
         the rights granted to you under the License to provide to third parties,
         for a fee or other consideration (including without limitation fees for
         hosting or consulting/support services related to the Software), a
         product or service whose value derives, entirely or substantially, from
         the functionality of the Software. Any license notice or attribution
         required by the License must also include this Commons Clause License
         Condition notice.
         
         Software:    sabbatical
         License:     Apache License 2.0
         Licensor:    Whitman Bohorquez
         
         
                                       Apache License
                                 Version 2.0, January 2004
                              http://www.apache.org/licenses/
         
         TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
         
         1. Definitions.
         
            "License" shall mean the terms and conditions for use, reproduction,
            and distribution as defined by Sections 1 through 9 of this document,
            plus the Commons Clause License Condition v1.0 above.
         
            "Licensor" shall mean the copyright owner or entity authorized by the
            copyright owner that is granting the License.
         
            "Legal Entity" shall mean the union of the acting entity and all other
            entities that control, are controlled by, or are under common control
            with that entity. For the purposes of this definition, "control" means
            (i) the power, direct or indirect, to cause the direction or management
            of such entity, whether by contract or otherwise, or (ii) ownership of
            fifty percent (50%) or more of the outstanding shares, or (iii)
            beneficial ownership of such entity.
         
            "You" (or "Your") shall mean an individual or Legal Entity exercising
            permissions granted by this License.
         
            "Source" form shall mean the preferred form for making modifications,
            including but not limited to software source code, documentation source,
            and configuration files.
         
            "Object" form shall mean any form resulting from mechanical
            transformation or translation of a Source form, including but not
            limited to compiled object code, generated documentation, and
            conversions to other media types.
         
            "Work" shall mean the work of authorship, whether in Source or Object
            form, made available under the License, as indicated by a copyright
            notice that is included in or attached to the work (an example is
            provided in the Appendix below).
         
            "Derivative Works" shall mean any work, whether in Source or Object
            form, that is based on (or derived from) the Work and for which the
            editorial revisions, annotations, elaborations, or other modifications
            represent, as a whole, an original work of authorship. For the purposes
            of this License, Derivative Works shall not include works that remain
            separable from, or merely link (or bind by name) to the interfaces of,
            the Work and Derivative Works thereof.
         
            "Contribution" shall mean any work of authorship, including the
            original version of the Work and any modifications or additions to
            that Work or Derivative Works thereof, that is intentionally submitted
            to the Licensor for inclusion in the Work by the copyright owner or by
            an individual or Legal Entity authorized to submit on behalf of the
            copyright owner. For the purposes of this definition, "submitted" means
            any form of electronic, verbal, or written communication sent to the
            Licensor or its representatives, including but not limited to
            communication on electronic mailing lists, source code control systems,
            and issue tracking systems that are managed by, or on behalf of, the
            Licensor for the purpose of discussing and improving the Work, but
            excluding communication that is conspicuously marked or otherwise
            designated in writing by the copyright owner as "Not a Contribution."
         
            "Contributor" shall mean Licensor and any individual or Legal Entity on
            behalf of whom a Contribution has been received by the Licensor and
            subsequently incorporated within the Work.
         
         2. Grant of Copyright License. Subject to the terms and conditions of
            this License (including the Commons Clause License Condition), each
            Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
            no-charge, royalty-free, irrevocable copyright license to reproduce,
            prepare Derivative Works of, publicly display, publicly perform,
            sublicense, and distribute the Work and such Derivative Works in
            Source or Object form.
         
         3. Grant of Patent License. Subject to the terms and conditions of this
            License (including the Commons Clause License Condition), each
            Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
            no-charge, royalty-free, irrevocable (except as stated in this section)
            patent license to make, have made, use, offer to sell, sell, import,
            and otherwise transfer the Work, where such license applies only to
            those patent claims licensable by such Contributor that are necessarily
            infringed by their Contribution(s) alone or by combination of their
            Contribution(s) with the Work to which such Contribution(s) was
            submitted. If You institute patent litigation against any entity
            (including a cross-claim or counterclaim in a lawsuit) alleging that
            the Work or a Contribution incorporated within the Work constitutes
            direct or contributory patent infringement, then any patent licenses
            granted to You under this License for that Work shall terminate as of
            the date such litigation is filed.
         
         4. Redistribution. You may reproduce and distribute copies of the Work
            or Derivative Works thereof in any medium, with or without
            modifications, and in Source or Object form, provided that You meet
            the following conditions:
         
            (a) You must give any other recipients of the Work or Derivative Works
                a copy of this License; and
         
            (b) You must cause any modified files to carry prominent notices
                stating that You changed the files; and
         
            (c) You must retain, in the Source form of any Derivative Works that
                You distribute, all copyright, patent, trademark, and attribution
                notices from the Source form of the Work, excluding those notices
                that do not pertain to any part of the Derivative Works; and
         
            (d) If the Work includes a "NOTICE" text file as part of its
                distribution, then any Derivative Works that You distribute must
                include a readable copy of the attribution notices contained
                within such NOTICE file, excluding any notices that do not pertain
                to any part of the Derivative Works, in at least one of the
                following places: within a NOTICE text file distributed as part of
                the Derivative Works; within the Source form or documentation, if
                provided along with the Derivative Works; or, within a display
                generated by the Derivative Works, if and wherever such third-party
                notices normally appear. The contents of the NOTICE file are for
                informational purposes only and do not modify the License. You may
                add Your own attribution notices within Derivative Works that You
                distribute, alongside or as an addendum to the NOTICE text from
                the Work, provided that such additional attribution notices cannot
                be construed as modifying the License.
         
            You may add Your own copyright statement to Your modifications and may
            provide additional or different license terms and conditions for use,
            reproduction, or distribution of Your modifications, or for any such
            Derivative Works as a whole, provided Your use, reproduction, and
            distribution of the Work otherwise complies with the conditions stated
            in this License (including the Commons Clause License Condition).
         
         5. Submission of Contributions. Unless You explicitly state otherwise,
            any Contribution intentionally submitted for inclusion in the Work by
            You to the Licensor shall be under the terms and conditions of this
            License, without any additional terms or conditions. Notwithstanding
            the above, nothing herein shall supersede or modify the terms of any
            separate license agreement you may have executed with Licensor
            regarding such Contributions.
         
         6. Trademarks. This License does not grant permission to use the trade
            names, trademarks, service marks, or product names of the Licensor,
            except as required for reasonable and customary use in describing the
            origin of the Work and reproducing the content of the NOTICE file.
         
         7. Disclaimer of Warranty. Unless required by applicable law or agreed
            to in writing, Licensor provides the Work (and each Contributor
            provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
            OR CONDITIONS OF ANY KIND, either express or implied, including,
            without limitation, any warranties or conditions of TITLE,
            NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
            PURPOSE. You are solely responsible for determining the appropriateness
            of using or redistributing the Work and assume any risks associated
            with Your exercise of permissions under this License.
         
         8. Limitation of Liability. In no event and under no legal theory,
            whether in tort (including negligence), contract, or otherwise, unless
            required by applicable law (such as deliberate and grossly negligent
            acts) or agreed to in writing, shall any Contributor be liable to You
            for damages, including any direct, indirect, special, incidental, or
            consequential damages of any character arising as a result of this
            License or out of the use or inability to use the Work (including but
            not limited to damages for loss of goodwill, work stoppage, computer
            failure or malfunction, or any and all other commercial damages or
            losses), even if such Contributor has been advised of the possibility
            of such damages.
         
         9. Accepting Warranty or Additional Liability. While redistributing the
            Work or Derivative Works thereof, You may choose to offer, and charge
            a fee for, acceptance of support, warranty, indemnity, or other
            liability obligations and/or rights consistent with this License
            (including the Commons Clause License Condition). However, in
            accepting such obligations, You may act only on Your own behalf and
            on Your sole responsibility, not on behalf of any other Contributor,
            and only if You agree to indemnify, defend, and hold each Contributor
            harmless for any liability incurred by, or claims asserted against,
            such Contributor by reason of your accepting any such warranty or
            additional liability.
         
         END OF TERMS AND CONDITIONS
         
         Copyright 2026 Whitman Bohorquez
         
         Licensed under the Apache License, Version 2.0, modified by the
         Commons Clause License Condition v1.0 (the "License"); you may not
         use this file except in compliance with the License. You may obtain
         a copy of the Apache License at
         
             http://www.apache.org/licenses/LICENSE-2.0
         
         Unless required by applicable law or agreed to in writing, software
         distributed under the License is distributed on an "AS IS" BASIS,
         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
         See the License for the specific language governing permissions and
         limitations under the License.
License-File: LICENSE
Keywords: ai,agents,cli,orchestration,llm,automation
Author: elpapi42
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Dist: alembic (>=1.13.0)
Requires-Dist: databases[aiosqlite] (>=0.9.0)
Requires-Dist: fastapi (>=0.111.0)
Requires-Dist: google-adk[extensions] (>=0.1.0)
Requires-Dist: httpx (>=0.27.0)
Requires-Dist: mcp (>=1.26.0)
Requires-Dist: pydantic (>=2.7.0)
Requires-Dist: sqlalchemy (>=2.0.0)
Requires-Dist: typer[all] (>=0.12.0)
Requires-Dist: uvicorn[standard] (>=0.30.0)
Project-URL: Homepage, https://github.com/elpapi42/sabbatical
Project-URL: Issues, https://github.com/elpapi42/sabbatical/issues
Project-URL: Repository, https://github.com/elpapi42/sabbatical
Description-Content-Type: text/markdown

# Sabbatical

**Stop pair programming with AI. Start managing it.**

---

You open Claude Code. You type a request. You wait. It responds. You react. You wait again. For every task, you're stuck in a synchronous loop — blocked while it works, blocking it while you think.

The workaround? More sessions. You open three Claude Code tabs, four Cursor windows, juggling contexts. Now you're a human load balancer — remembering which session is doing what, re-explaining context when one drifts, copy-pasting results between them. You traded one bottleneck for a coordination problem.

Sabbatical is a different model. You build a team of AI agents once — a lead developer, a backend specialist, a test writer, whatever your project needs. Then you dispatch tasks to them the same way a tech lead assigns tickets. The agents pick up work, collaborate through `@mentions`, hand off between specialists, and surface results when they're done, blocked, or ready for review.

Meanwhile, you're doing what you're actually good at — using Claude Code to plan the next initiative, breaking a complex objective into tasks your team can execute, reviewing a PR from another team, writing a design doc. Your AI tool becomes your thinking partner for planning. Your Sabbatical team handles the execution. You're not context-switching between AI sessions. You're managing a team through tasks.

It's the difference between juggling five chat windows and having a team that works from a backlog. One scales with you. The other scales against you.

**You, in Claude Code:**
```
You:         "Add idempotency keys to the charge endpoint.
              Assign it to the payments team."

Claude Code:  ✅ Task PAYM-0003 created and assigned to lead_dev.
```

You close the tab. You go scope the billing migration.

**Meanwhile, in the background — the Sabbatical task thread:**
```
lead_dev:      Scoped the work. Needs DB migration + handler logic. @backend_dev
backend_dev:   Added idempotency_keys table, wrapped /charges POST
               in key check. @test_writer
test_writer:   Tests passing for duplicate charge rejection
               and key expiry. @lead_dev
lead_dev:      Reviewed. Ship it. @user
```

**20 minutes later, back in Claude Code:**
```
You:         "What's the status on the payments team?"

Claude Code:  PAYM-0003 "Add idempotency keys" — ✅ done.
              4 agent handoffs · 5 files changed · all tests passing.
```

Three agents. Zero interruptions. You were working on something else the whole time.

---

## Use It Your Way

Sabbatical isn't a new tool competing for your attention. It's infrastructure you control from wherever you already work.

**From your AI tool.** Claude Code, Codex, Gemini, Cursor, Windsurf — anything that speaks MCP. Your AI tool becomes the manager: it builds orgs, dispatches tasks, monitors progress, and intervenes when agents get stuck. You stay in one place and talk in natural language.

**From the CLI.** If you live in the terminal, the full-featured CLI gives you direct control over every operation — organizations, agents, tasks, runs. No middleman.

**From anything you build.** Sabbatical exposes a complete HTTP REST API. Build a TUI, a web dashboard, an IDE extension — whatever fits your workflow. The API covers every operation available in the CLI and MCP server, so nothing is off-limits.

All three interfaces talk to the same core, the same database, the same dispatcher. Mix and match as you like.

---

## Quick Start

### Install and start

```bash
pipx install sabbatical
export OPENROUTER_API_KEY="sk-or-your-key"
sabbatical api up
```

The API server starts in the background. The dispatcher daemon starts automatically and begins polling for queued tasks. Check that everything is running:

```bash
sabbatical status
```

### Connect your AI tool

**Claude Code:**
```bash
claude mcp add sabbatical -- sabbatical mcp
```

**Cursor, Windsurf, or any MCP client:**
```json
{
  "mcpServers": {
    "sabbatical": {
      "command": "sabbatical",
      "args": ["mcp"]
    }
  }
}
```

Your AI tool now has 22 MCP operations to build teams, dispatch tasks, and monitor agents. The skill files are automatically installed to `~/.sabbatical/skill/` on first run. To install them into a specific project directory instead:

```bash
sabbatical install-skill --path ./your-project
```

For Claude Code, add this to your `CLAUDE.md`:

```
## Sabbatical — AI Agent Orchestration

Sabbatical is installed and available for managing teams of AI agents that execute work autonomously.

Read and follow the instructions in ~/.sabbatical/skill/SKILL.md for using Sabbatical.

Key concepts:
- "Organization" / "team" / "squad" = a Sabbatical organization — a group of agents scoped to a codebase.
- "Agent" / "specialist" / "dev" = a Sabbatical agent — a stateless AI worker defined by an instructions file.
- "Task" / "ticket" / "issue" / "work item" = a Sabbatical task — a unit of work dispatched to an organization.
- "Assign to the team" / "hand this off" / "dispatch this" = create a task in the relevant organization.
- "Check on" / "status" / "how's it going" = list or view tasks to report progress.

When the user talks about assigning work, creating tasks, checking progress, building teams,
or managing agents — use the Sabbatical MCP tools. Match informal language to the right operation.
```

### Build your first team

Organizations map to real team boundaries — a backend platform team, a payments squad, a mobile client team — each scoped to a codebase directory.

```bash
sabbatical organization create payments \
  --workspace-path /absolute/path/to/payments-service \
  --description "Payments service team — API, billing logic, Stripe integration"

sabbatical agent add lead_dev \
  --organization payments \
  --instructions ./agents/lead_dev.md

sabbatical agent add backend_dev \
  --organization payments \
  --instructions ./agents/backend_dev.md \
  --boss lead_dev

sabbatical agent add test_writer \
  --organization payments \
  --instructions ./agents/test_writer.md \
  --boss lead_dev
```

Or just tell Claude Code: *"Set up a Sabbatical org for the payments service with a lead, a backend specialist, and a test writer."* It does it through MCP.

You build the team once. Then you feed it work — daily, across sprints, across initiatives.

### Dispatch your first task

```bash
sabbatical task create "Add idempotency keys to charge endpoint" \
  --organization payments \
  --description "Wrap the /charges POST handler in idempotency logic..."
```

The task auto-assigns to `lead_dev` (the root agent) and enters the dispatch queue. Agents start collaborating immediately. Check back later:

```bash
sabbatical task list --organization payments
sabbatical task view PAYM-0001
```

---

## Manage a Backlog, Not a Chat Session

This is where the model pays off. You're not dispatching one task and watching it. You're stacking work across teams like a tech lead.

```bash
# Monday morning — queue up the week
sabbatical task create "Add idempotency keys to charge endpoint" \
  --organization payments \
  --description "Wrap the /charges POST handler in idempotency logic..."

sabbatical task create "Migrate webhook handler to async" \
  --organization payments \
  --description "The Stripe webhook handler is synchronous and blocking..."

sabbatical task create "Add retry budget metrics to dashboard" \
  --organization platform \
  --description "Expose retry budget counters from the circuit breaker..."
```

Three tasks, two teams. The agents pick them up, collaborate, hand off, and surface results — while you're in a design review for something else entirely. When you come back:

```bash
sabbatical task list --organization payments --status done
sabbatical task list --organization platform --status open
```

This is the real value. Not "AI does your work while you nap." It's: **you can operate across multiple initiatives concurrently without the cognitive overhead of managing a dozen AI sessions.** The team structure absorbs that complexity. You manage tasks, not conversations.

And here's the workflow that makes it click: use your current AI tool — Claude Code, Codex, Gemini, whatever — for what it's great at: **planning**. Talk through the problem, break a complex objective into smaller tasks, write detailed specs. Then offload the execution to your Sabbatical organization. Your AI tool thinks with you. Your agents do the work. Planning stays interactive. Execution runs in the background.

---

## Cheaper Models, Same Quality

Orchestrating a team of specialized agents comes with a bonus you might not expect: **you can get away with cheaper models.**

A single agent working alone needs to be smart enough to handle everything — architecture decisions, implementation details, edge cases, testing. That demands a flagship model. But a team of agents acts as its own safety net. The lead reviews the backend dev's work. The test writer catches what the implementer missed. Given clear instructions and enough context in the thread, agents on smaller models course-correct each other — and the final output holds up to the quality you'd expect from models that cost 10x more.

The team structure isn't just an organizational tool. It's a cost multiplier.

---

## How It Works

At the center is a **core library** — organizations, agents, tasks, the dispatcher, the execution engine. On top of it, three interfaces serve different users:

```
         ┌──────────┐   ┌─────────────┐   ┌──────────────────┐
         │   CLI    │   │ HTTP Server │   │   MCP Server     │
         │          │   │             │   │                  │
         │ terminal │   │ build tools │   │ connect AI tools │
         │ users    │   │ on top      │   │ (Claude Code,    │
         │          │   │             │   │  Cursor, etc.)   │
         └────┬─────┘   └──────┬──────┘   └────────┬─────────┘
              │                │                    │
              ▼                ▼                    ▼
         ┌───────────────────────────────────────────────┐
         │              Sabbatical Core                  │
         │                                               │
         │  Organizations · Agents · Tasks · Comments    │
         │  Dispatcher · Worker Threads · Execution      │
         │                                               │
         │  ┌───────────────────────────────────────┐    │
         │  │           SQLite Database              │    │
         │  └───────────────────────────────────────┘    │
         └───────────────────────────────────────────────┘
```

**Agents are stateless.** Every run is a fresh instance. Context comes from the agent's instructions file and the task's comment thread — no hidden state, no drift between runs.

**Agents collaborate through `@mentions`.** When an agent finishes, the system reads the last valid `@tag` from its last comment and routes the task to that agent (or `@user`). No workflow engine, no DAG — just a comment thread and a handoff protocol.

**The thread is a safety net.** If an agent's last comment has no valid tag, the system scans the thread for agents who were mentioned but haven't run since their mention, and routes to the most recently mentioned one. If no candidates remain, it escalates to the agent's boss, then to you.

**Everything runs locally.** SQLite database, local file access, shell commands against your actual codebase. No cloud dependency. All LLM calls route through [OpenRouter](https://openrouter.ai), so you pick the model.

For the full picture, see [Architecture](docs/architecture.md) and [Core Concepts](docs/concepts.md).

---

## Documentation

| Document | What it covers |
|----------|----------------|
| [Core Concepts](docs/concepts.md) | Organizations, agents, tasks, runs, comments, and the collaboration model |
| [Architecture](docs/architecture.md) | System design, component structure, and key design decisions |
| [Task Lifecycle](docs/task-lifecycle.md) | State machine, transitions, routing rules, failure modes, and crash recovery |
| [Agent Execution](docs/agent-execution.md) | Runtime, tools, context building, and the worker model |
| [Dispatcher](docs/dispatcher.md) | Polling loop, concurrency control, heartbeats, and daemon management |
| [Configuration](docs/configuration.md) | All config options, model selection, and tuning tips |
| [CLI Reference](docs/cli-reference.md) | Complete reference for all CLI commands |
| [API Reference](docs/api-reference.md) | Complete reference for all REST API endpoints |
| [MCP Reference](docs/mcp-reference.md) | Complete reference for all MCP server tools |

---

## Prerequisites

- Python 3.12+
- An [OpenRouter](https://openrouter.ai) API key

## Contributing

Issues and PRs welcome. If you're building with Sabbatical or have feedback on the collaboration model, [open a discussion](https://github.com/elpapi42/sabbatical/discussions).

