Metadata-Version: 2.4
Name: inscript
Version: 0.5.0
Summary: Universal agent activity ledger. Records what AI agents do.
Author: Andrew Park
License-Expression: MIT
Project-URL: Homepage, https://github.com/aardpark/inscript
Keywords: ai,agent,context,mcp,claude,session,tracking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# inscript

Universal agent activity ledger.

When an AI agent works on code, **inscript** records everything: which project, which files, what changed. Any tool can read `~/.inscript/` for context.

## Install

```bash
pip install inscript
```

## What it records

```
~/.inscript/
  active_project              ← which codebase right now
  active_session              ← current session ID
  config.toml                 ← retention policy
  sessions/
    <session-id>/
      meta.json               ← start time, project, status
      touches.jsonl           ← every file read/edit/write
      diffs.jsonl             ← raw changes (Edit old→new, Write content hash)
      summary.json            ← stats written on session end
  overlap/
    <project-hash>.jsonl      ← when 2+ sessions touch the same files
```

## Setup

```bash
inscript init    # configure retention, storage, diffs
```

Then add hooks to `~/.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{ "type": "command", "command": "inscript-hook" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Read|Edit|Write|Glob|Grep",
        "hooks": [{ "type": "command", "command": "inscript-hook", "async": true }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "inscript-hook" }]
      }
    ]
  }
}
```

## CLI

```bash
inscript              # status: active project + session
inscript log          # activity log for current session
inscript log <id>     # activity log for a specific session
inscript overlap      # show file collisions across sessions
inscript export <id>  # export session as markdown
inscript cleanup      # enforce retention policy
inscript init         # setup wizard
```

## Python API

```python
from inscript_pkg import active_project, active_session, list_sessions

project = active_project()    # Path or None
session = active_session()    # session ID or None
all_sessions = list_sessions()  # [{session_id, start_time, project, status}, ...]
```

## How it works

Three Claude Code hooks write to `~/.inscript/`:

- **SessionStart** → creates `sessions/<id>/meta.json`
- **PostToolUse** → appends to `touches.jsonl` and `diffs.jsonl`
- **Stop** → writes `summary.json` with session stats

Any MCP server, script, or tool can read these files. No coordination needed. The agent doesn't know inscript exists.

## Overlap detection

When two Claude Code sessions work on the same project simultaneously, inscript records which files both sessions touch. Run `inscript overlap` to see collisions.
