Metadata-Version: 2.4
Name: startq
Version: 0.3.0
Summary: Never lose your AI chats or work again. Boot, monitor, and shut down your AI workflow.
Author-email: Phil Hills <phil@philhills.ai>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Phil-Hills/startq
Project-URL: Issues, https://github.com/Phil-Hills/startq/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# StartQ

> Never lose your AI chats or work again.

## Your AI Workflow Is a Computer. Boot It Like One.

Think about what happens when you turn on your PC.

The BIOS runs. It checks the hardware. The OS loads drivers, mounts disks, reads your settings, restores your last session. Everything you were working on comes back exactly where you left it. Then you work. Then you shut down — and the OS saves your state so tomorrow picks up clean.

Now think about your AI development workflow.

You have API connections. Database credentials. Multiple AI models — Claude, Gemini, GPT, local models. You have agent scripts, deployment pipelines, live services, project configs across different repos. You have context — decisions made yesterday, bugs found last week, architecture choices from last month.

Every time you start a new AI session, all of that context is gone. You re-explain everything. The agent doesn't remember what you built yesterday. An IDE update wipes your environment. You lose hours.

**StartQ treats your AI workflow like a computer. Boot it. Monitor it. Shut it down.**

```
StartQ          AutoQ           EndQ
  │               │               │
  ▼               ▼               ▼
POWER ON       MONITORING      SHUTDOWN
  │               │               │
  ▼               ▼               ▼
Health check    Watch agents    Capture state
Load context    Review work     Git snapshot
Verify auth     Surface issues  Sign receipt
Spawn daemons   Auto-recover    Sync to cloud
  │               │               │
  ▼               ▼               ▼
 Ready          Running         Saved
```

Three Python scripts. That's it.

## The Lifecycle

### StartQ — Power On

```bash
startq boot
```

Like pressing the power button on your PC. StartQ runs a boot sequence:

1. **POST** — checks that your local brain exists and is writable
2. **Auth** — verifies your identity from config
3. **Memory** — loads your last session's context, verifies its SHA-256 signature
4. **Daemons** — spawns any background scripts you've configured
5. **Handoff** — your AI agent starts with full context from yesterday

You don't re-explain your project. You don't re-paste your API keys. You don't re-describe your architecture. The agent already knows.

### AutoQ — Monitor

While you work, AutoQ watches your session:

- Surfaces recurring workflow patterns
- Reviews agent behavior for quality
- Catches drift before it becomes a problem
- Promotes good patterns into reusable workflows

Think of it as Task Manager for your AI workflow. It runs in the background and makes sure things stay on track.

### EndQ — Shutdown

```bash
startq end -c "Built the payment API. Stripe integration complete. Deploy tomorrow."
```

Like shutting down your PC properly instead of yanking the power cord:

1. **State capture** — your summary becomes persistent context
2. **Git snapshot** — current branch, uncommitted files, all recorded
3. **Signing** — SHA-256 hash ensures nobody tampers with the receipt
4. **Cloud sync** — optionally pushes to a hosted brain for multi-machine access
5. **Receipt** — a signed JSON file in `.startq/brain/` proves the session existed

Tomorrow when you run `startq boot`, all of this loads automatically. Zero amnesia.

## Why This Matters — A Real Story

On May 19, 2026, Antigravity IDE pushed an update that wiped environment state for developers mid-session. Workflows deleted. Context gone. Developers lost hours of work.

I didn't lose a single thing.

Because StartQ had already persisted my session state, agent context, and workflow definitions to local memory before the update hit. When the environment came back up, I ran `startq boot`, and everything was exactly where I left it.

> StartQ is insurance for your AI workflow. Your context survives IDE crashes, model swaps, environment resets, and cloud outages.

## Install

```bash
pip install startq
```

Zero dependencies. Pure Python standard library.

## Quick Start

```bash
# Initialize your project brain
startq init

# Start your session (loads previous context)
startq boot

# ... do your work with any AI tool ...

# Save your session (captures context + git state)
startq end -c "What I accomplished today."
```

## Cloud Sync (v0.2.0)

Connect to a hosted brain for multi-machine, multi-agent persistence:

```bash
# One-time setup
startq upgrade --url https://your-brain-endpoint.run.app --key sk-xxx

# Now boot and end auto-sync to cloud
startq boot      # pulls latest context from cloud
startq end -c "..." # pushes session to cloud

# Force local-only when needed
startq boot --local
```

## Check Your Status

```bash
startq status
```

Shows your identity, session count, cloud connection status, and latest session context.

## What Gets Persisted

| Data | Where | Format |
|------|-------|--------|
| Session context | `.startq/brain/<uuid>.json` | Signed JSON |
| Git branch + dirty files | Inside session receipt | Embedded |
| Agent identity | `.startq/config.json` | JSON |
| Cloud config | `.startq/config.json` | JSON |
| Init state | `.startq/state.json` | JSON |

## The PC Boot Analogy

| PC Boot | StartQ |
|---------|--------|
| BIOS POST | `startq boot` — health check |
| Load OS | Load last session context |
| Mount drives | Connect to cloud brain |
| Restore session | Inject context into agent |
| Task Manager | AutoQ — monitor workflows |
| Save & Shutdown | `startq end` — sign + persist |
| Hibernate | Session receipt in `.startq/brain/` |
| Wake from sleep | Next `startq boot` — instant context |

## Features

- **Local First** — your brain is a local JSON directory. No cloud required.
- **Cryptographic Integrity** — every session receipt is SHA-256 signed. Tampering detected on boot.
- **Cloud Sync** — optionally connect to any REST endpoint for multi-machine persistence.
- **Universal** — works with Claude, Cursor, Antigravity, Gemini CLI, or any AI tool.
- **Daemons** — spawn background scripts on boot, like systemd for your AI workflow.
- **Git Aware** — captures branch and uncommitted files automatically.
- **Zero Dependencies** — pure Python standard library. No pip packages. No curl. No YAML.

## How It Works

These are just Python scripts. No magic. No framework lock-in.

- `startq/brain.py` — reads and writes signed JSON session files
- `startq/cli.py` — the command-line interface
- `startq/cloud_brain.py` — optional REST client for cloud sync

You can read the source in 10 minutes. You can fork it and customize it in 20. That's the point.

## License

MIT License. Built in Seattle by [Phil Hills](https://github.com/Phil-Hills).
