Metadata-Version: 2.4
Name: startq
Version: 0.1.0
Summary: Persist session context across AI agent runs. Local-first, zero dependencies.
Author-email: Phil Hills <phil@philhills.ai>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# StartQ

> Never lose your AI chats or work again.

Every time you start a new AI agent session, you repeat yourself. You re-explain the project. You re-paste the context. You hope the agent remembers what happened yesterday.

It usually doesn't.

**StartQ fixes that.**

## 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 across the platform 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 — 28 workflow files, all agent configurations, full session history.

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

## 60-Second Install

```bash
pip install startq
```

Initialize your local memory (Brain) in your project directory:

```bash
startq init
```

Boot your agent workflow:

```bash
startq boot
```

When you are finished with your session, sync the persistent memory:

```bash
startq end -c "Finished refactoring the database schemas."
```

## How It Works

```
Session 1                          Session 2
─────────                          ─────────
You work with AI agent             You start a NEW agent session
    │                                  │
    ▼                                  ▼
startq end -c "summary"           startq boot
    │                                  │
    ▼                                  ▼
State written to .startq/brain/    State loaded from .startq/brain/
    │                                  │
    ▼                                  ▼
SHA-256 signed receipt             Signature verified ✓
                                       │
                                       ▼
                                   Agent has FULL context
                                   from Session 1. No amnesia.
```

## Features

- **Local First**: Your Brain is a local JSON directory (`.startq/brain/`). No cloud dependencies, no lock-in.
- **Cryptographic Integrity**: Every session receipt is SHA-256 signed. Tampering is detected on boot.
- **Universal Agnosticism**: Point any agent (Claude Code, Cursor, Antigravity, Gemini CLI, or custom scripts) to `.startq/` to share context across sessions.
- **Daemons (Systemd for AI)**: Add scripts to `.startq/config.json` under `"daemons"`, and StartQ will spawn them as detached background runners on boot.
- **Git State Capture**: `startq end` automatically snapshots your current branch and uncommitted files — so the next session knows exactly where you left off.
- **Zero Dependencies**: Pure Python standard library. No pip packages. No curl. No YAML.

## 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 |
| Init state | `.startq/state.json` | JSON |

## The Problem StartQ Solves

AI agents have **no memory between sessions**. Every new chat is a blank slate. This means:

- You re-explain your project structure every time
- You lose the decisions made in previous sessions
- An IDE update or crash wipes your workflow context
- Context windows fill up re-establishing what was already known

StartQ gives your agents a **persistent local brain** that survives across sessions, across tools, and across crashes.

## License

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