ClawTab Documentation

Quick Start

Prerequisites

Installation

Homebrew (recommended)

brew install --cask tonisives/tap/clawtab

This installs the clawtab GUI app, cwtctl CLI, and cwttui terminal UI.

Build from source

pnpm install
cargo tauri build

Both methods produce three binaries:

Binary Purpose
clawtab GUI app (Tauri window)
cwtctl CLI for headless control
cwttui Terminal UI (ratatui)

Setup Wizard

On first launch, the setup wizard walks through:

  1. Tools -- Detects installed tools (editors, terminals, tmux, claude, gopass, aerospace)
  2. Notifications -- Choose notification target: ClawTab App (push), Telegram (bot), or skip
  3. Hello World -- Creates and runs a test job to verify the setup
  4. Web Browse -- Creates an AI job that fetches Hacker News
  5. Done -- Saves settings.yaml, marks setup complete

The wizard auto-detects tools and shows version + path for each. Missing tools can be installed via Homebrew directly from the UI.

Creating Your First Job

Create a new job

Binary job (run a script)

  1. Open the Jobs panel
  2. Click "New Job"
  3. Set type to Binary
  4. Set path to your script (e.g., /path/to/backup.sh)
  5. Choose a weekly calendar recurrence or set a cron expression (e.g., 0 0 * * * for daily at midnight)
  6. Save

Claude job (run a prompt)

  1. Set type to Claude
  2. Set path to a text file containing your prompt
  3. The prompt file content is passed to claude via $(cat /path/to/prompt.txt)
  4. Runs inside a tmux window named cwt-<project>

Folder job (project-based AI agent)

  1. In ClawTab, click "New Job" and set type to Folder
  2. Browse to your project root
  3. Enter a Job Name (e.g., "deploy", "lint")
  4. Edit job.md with your agent instructions (stored at ~/.config/clawtab/jobs/<slug>/<job-name>/job.md)
  5. Optionally add shared context in ~/.config/clawtab/jobs/<slug>/context.md (applies to all jobs in the project)
  6. The job runs Claude from the project root with context inlined from central config

All job files (config, prompts, context) are stored centrally at ~/.config/clawtab/jobs/.

Scheduled agent job from the CLI

In a project directory, run cwtctl jobs create for an interactive form. Enter the name and a cron expression or one-time date, then write the job description in nvim. The command joins the nearest configured group whose project folder contains the current directory. If none matches, it creates a group from the directory name.

You can also supply the fields directly:

cwtctl jobs create --name daily-review --cron '0 9 * * *' --description-file review.md
cwtctl jobs create --name follow-up --at '2026-10-02 09:00' --description 'Check the results'
cat task.md | cwtctl jobs create --name task --at '2026-10-02T09:00:00+07:00' --description-stdin

--at takes a future local date and time or RFC 3339 timestamp. A one-time job removes its config after the agent starts by default, while the tmux pane and run history remain available. Pass --keep-config to retain a disabled job. See CLI & TUI for details.

Running a Job

  • GUI: Click "Run Now" on any job
  • CLI: cwtctl jobs run <group>/<name>
  • TUI: Select job, press r
  • Telegram: Send /run <name> to your bot
  • Schedule: Automatically triggered by the job's cron expression, calendar recurrence, or one-time date

Checking Status

cwtctl jobs status

Status values: idle, running, success, failed, paused.