Metadata-Version: 2.4
Name: clu-cli
Version: 1.23.0
Summary: Intent-oriented code review for AI-assisted development
Requires-Python: >=3.13
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: orjson>=3.10
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.7
Requires-Dist: tomli-w>=1.0
Description-Content-Type: text/markdown

# Clu CLI

## Architecture

The CLI now follows a layered layout:

- `src/clu/cli/` contains Click command adapters only.
- `src/clu/lib/` contains feature orchestration and command entrypoints.
- `src/clu/models/` contains flat Pydantic models and enums.
- `src/clu/utils/` contains shared pure helpers.
- `src/clu/api/` contains backend auth and sync clients.
- `src/clu/store/` contains SQLite repositories and the store facade.
- `src/clu/adapter/`, `src/clu/git.py`, and `src/clu/transcript.py` remain
  infrastructure-facing modules used by the library layer.

## Commands

1. `clu auth`
3. `clu install --global` (default is in the current directory) 
2. `clu append --agent codex/claude/gemini`
3. `clu flush`

Config path: `$HOME/.clu/config.toml` -- use this to store any secrets, preferences etc.

## Happy Path Flow

- User does `clu auth login` -- this opens a web based oauth login
  - After login, the CLI should silently refresh expired access tokens using the stored refresh token.
- User does `clu auth status` to verify the current session and test refresh behavior.
- User does `clu install` in the project directory, or `clu install --global` if they want to install it in the gobal config.
  - This asks the user what agent to install it for (TUI style picker)
    - Installing for claude code modifies the `.claude/settings.json` and installs the `clu append` command as the hook for all events and all matches (an example for the settings is added below)
    - Hooks Reference for Claude: https://code.claude.com/docs/en/hooks#hook-events
- The `clu append` command reads the hook payload from stdin, stores the raw
  event locally, and incrementally parses transcript messages into SQLite.
- The `clu flush` command syncs dirty sessions to `/sessions` and then
  bulk-uploads dirty messages to `/session-messages` in batches.

## Eventual Direction

This SQLite file is the local capture layer. The backend correlates the synced
session and message data with GitHub PR events later; the CLI no longer builds
or submits a final changeset payload itself.


## Settings JSON

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "PermissionDenied": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "SubagentStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "TaskCreated": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "TaskCompleted": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "StopFailure": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "TeammateIdle": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "InstructionsLoaded": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "FileChanged": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "WorktreeCreate": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "WorktreeRemove": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "PostCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "Elicitation": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "ElicitationResult": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/junaidrahim/Code/sandbox/log-hook.sh"
          }
        ]
      }
    ]
  }
}
```
