Metadata-Version: 2.4
Name: claude-gate
Version: 1.0.3
Summary: Gate Claude Code tool use behind Slack approvals and enable remote task execution from your phone
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: slack_sdk>=3.27
Requires-Dist: openai>=1.40
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-mock>=3; extra == "dev"
Dynamic: license-file

# claude-gate

Gate [Claude Code](https://claude.ai/code) tool use behind approvals and control it remotely from your phone via Slack DMs.

## What it does

- **Remote task execution** — start a session from Slack, send a task as text or 🎙️ voice message, confirm it with a button, and Claude Code runs it on your machine.
- **Interactive sessions** — `!start-session` opens a back-and-forth conversation with Claude directly from Slack. Follow-up messages run instantly within the same session.
- **Task approval** — every task shows a confirmation card with **Run Task / Cancel** before anything executes. Nothing runs without your explicit approval.
- **Per-session model switching** — switch between Opus, Sonnet, and Haiku mid-session with `!model opus`. Resets to default when the session ends.

## Install

```bash
pipx install claude-gate
```

## Setup

**1. Create a Slack app**

Run the guided setup to get the manifest and step-by-step instructions:

```bash
cg setup-slack
```

This prints the Slack app manifest and walks you through creating the app, installing it to your workspace, and copying the Bot Token (`xoxb-...`) and App Token (`xapp-...`).

**2. Initialise your project**

Run this from your project root:

```bash
cg init
```

This creates `.claude/` with all hook scripts and settings, then prompts for your tokens.

**3. Verify and start**

```bash
cg doctor   # confirms tokens work
cg up       # starts the daemon (Ctrl+C to stop)
cg up -d    # or run it in the background
```

## Slack commands

| Command | What it does |
|---|---|
| `!start-session` | Open an interactive back-and-forth session |
| `!end-session` | Close the interactive session |
| `!status` | Show what's running and elapsed time |
| `!output [N]` | Dump the last N lines of output |
| `!stop` | Kill the running task |
| `!log` | Show the path to the full task log file |
| `!revoke` | Revoke the "Allow All Session" flag early |
| `!model` | Show the current model for this session |
| `!model list` | List all available models |
| `!model opus` | Switch to Opus for this session |
| `!model sonnet` | Switch to Sonnet for this session |
| `!model haiku` | Switch to Haiku for this session |
| `!model reset` | Reset to default model (`claude-sonnet-4-6`) |
| 🎙️ Voice message | Transcribed via Whisper, confirmed via button (requires active session) |

## CLI reference

```
cg setup-slack     Print Slack app manifest and guided setup (start here)
cg init            Scaffold .claude/ and configure credentials
cg init --adopt    Existing .claude/ setup — just write .env
cg up              Start daemon in foreground
cg up -d           Start daemon detached (background)
cg down            Stop background daemon
cg status          Show daemon status and recent logs
cg logs [-f]       Tail activity and daemon logs
cg doctor          Verify tokens, deps, hook integrity
cg upgrade-hooks   Update hook files from package (backs up yours first)
cg remove          Remove claude-gate from the current project
```

## Requirements

- Python 3.10+
- A Slack workspace where you can install apps
- `claude` CLI installed and authenticated
- `notify-send` for desktop notifications (optional — `sudo apt install libnotify-bin`)
- OpenAI API key for voice message transcription (optional)

## How it works

Claude Code runs hooks before every tool use. The hooks in `.claude/hooks/` post an approval card to your Slack DM and wait for your response. The daemon (`cg up`) listens for incoming Slack messages and spawns `claude --print` subprocesses for remote tasks.

See [CLAUDE.md](CLAUDE.md) for the full architecture.

## License

MIT
