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
2. clu install --global (default is in the current directory)
3. clu append --agent codex/claude/gemini
4. 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

{
  "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"
          }
        ]
      }
    ]
  }
}