claw

A utility to control Gemini CLI from a Slackbot using threaded context in DMs.

Quick Start

1. Initialize Configuration: Run Claw for the first time to generate the default configuration file:

   bunx @m4j/claw

   This creates a file at ~/.m4j/claw/config.json.

2. Configure Providers: Edit ~/.m4j/claw/config.json and add your API keys and tokens. See the Configuration section for details.

3. Set Up Slack: Follow the Slack Bot Setup guide to get your Slack tokens.

4. Run:

   bunx @m4j/claw

Slack Bot Setup

To use Claw, you need to create a Slack App and connect it to your workspace.

1. Create the App

1. Go to Slack API: Your Apps.
2. Click Create New App and select From an app manifest.
3. Select your workspace.
4. Paste the following manifest (or use the slack-manifest.yaml file from the repo):

display_information:
  name: Claw Agent
  description: Coding Agent CLI Slack Bridge
  background_color: "#2c2d30"
features:
  bot_user:
    display_name: Claw
    always_online: true
oauth_config:
  scopes:
    bot:
      - im:history
      - chat:write
      - reactions:write
      - reactions:read
settings:
  event_subscriptions:
    bot_events:
      - message.im
  interactivity:
    is_enabled: true
  socket_mode_enabled: true

2. Get App-Level Token (appToken)

1. In your app settings, go to Basic Information.
2. Scroll down to App-Level Tokens and click Generate Token and Scopes.
3. Add the connections:write scope and give it a name (e.g., ClawSocket).
4. Copy the resulting token (starts with xapp-). This is your appToken.

3. Install App and Get Bot Token (token)

1. Go to Install App in the sidebar and click Install to Workspace.
2. Once installed, copy the Bot User OAuth Token (starts with xoxb-). This is your token.

4. Find Your IDs

• allowedUserId: In Slack, click your profile picture -> Profile -> More (...) -> Copy member ID.
• allowedWorkspaceId: You can find this by right-clicking your workspace name in the sidebar and selecting Copy link. The ID is the part starting with T (e.g., T01234567).

Configuration

Claw loads its configuration from ~/.m4j/claw/config.json.

Note: You must configure at least one provider for each of the following categories:

• LLM Provider: Used to generate branch names and perform light LLM tasks. Intended to point this at local ollama running a small model like gemma4.
• VCS Provider: GitHub or Bitbucket.
• Ticket Provider: Jira.
• Chat Provider: Slack (using the tokens from above).
• Agent Provider: The underlying agent to run (gemini, cline, rovodev, or claude).

Example Config Structure

{
  "webPort": 9095,
  "llmProviders": {
    "openai": {
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "NO-KEY",
      "model": "gemma4:e2b"
    }
  },
  "vcsProviders": {
    "github": {
      "token": "github_pat_..."
    }
  },
  "ticketProviders": {
    "jira": {
      "site": "your-site.atlassian.net",
      "email": "your-email@example.com",
      "apiToken": "..."
    }
  },
  "chatProviders": {
    "slack": {
      "token": "xoxb-...",
      "appToken": "xapp-...",
      "allowedUserId": "U12345678",
      "allowedWorkspaceId": "T12345678"
    }
  },
  "agentProviders": {
    "gemini": {
      "env": {
        "PATH": "/home/your_username/.nvm/versions/node/v24.14.0/bin/"
      }
    }
  },
  "emojis": {
    "ack": ["ok_hand", "thumbsup", "raised_hands", "point_up", "thought_balloon", "eyes"],
    "tool": "hammer_and_wrench",
    "agentProvider": {
      "rovodev": "robot_face",
      "gemini": "sparkles",
      "cline": "computer",
      "claude": "robot_face"
    },
    "ticketProvider": {
      "jira": "ticket"
    },
    "threadStatus": {
      "pending": "hourglass_flowing_sand",
      "working": "hammer_and_spanner",
      "completed": "white_check_mark",
      "error": "x",
      "idle": "sleeping",
      "pr-raised": "memo",
      "commented": "speech_bubble"
    }
  }
}

Systemd Service

Save this to /etc/systemd/system/claw.service:

[Unit]
Description=Claw slackbot agent
After=network.target

[Service]
Type=simple
User=your_username
Group=your_username
WorkingDirectory=/home/your_username
Environment=HOME=/home/your_username
ExecStart=/home/your_username/.bun/bin/bunx @m4j/claw
Restart=always

[Install]
WantedBy=multi-user.target

And then run

sudo systemctl daemon-reload
sudo systemctl enable --now claw