01
One YAML, every workflow.
Everything — triggers, filters, steps, templates — lives in sokuza.config.yaml. Version it, grep it, review it.
The pitch
速座 · sokuza — Japanese for "instant." A local-first engine that reacts to GitHub, Slack, webhooks and cron events by running Claude-powered workflows on your machine.
Why
You want an AI PR reviewer. An issue triager. A daily repo scout. An auto-respond loop on review comments. You don't want to glue ten SaaS products together, pay per seat, or hand your source code to a black box. Sokuza is a single binary you run yourself, configured by one YAML file.
Runs on
macOS · Linux · Windows · Node 20+
An integration emits an event. A workflow matches it. A sequence of actions runs. That's the whole model — the same shape for a one-line Slack notifier and a multi-step agentic PR loop.
An event fires from an integration — a PR opens, a Slack message arrives, a cron timer ticks, a custom webhook hits your endpoint.
YAML-defined sequences with matching filters (repo, branch, author, labels), conditional steps, and templated expressions that reference previous step outputs.
The work each step does — posting a comment, cloning a repo, sending a Slack reply, or running a full Claude Code agent with tool access inside a workdir.
Things that matter when you actually leave it running for weeks.
Everything — triggers, filters, steps, templates — lives in sokuza.config.yaml. Version it, grep it, review it.
Point at the Anthropic API directly, or fall back to the Claude Code CLI running on your machine. Your key, your bill, your sandbox.
Every review template uses a P1/P2/P3 priority system with deterministic approval logic. No more AI rubber-stamping.
The ai-agent action runs a Claude Code session inside a cloned repo with Read / Grep / Bash / Edit access. Agents can investigate, patch, and open PRs.
A GitHub trigger can fire a Slack action. A Slack command can trigger a code review. A cron timer can run a daily repo scout. One engine, many rails.
ai-pr-review, enforce-rules, daily-digest, dependency-review, security-audit, repo-scout, and ~20 more. Drop-in YAML you can copy and adapt.
Runs as a single Node process. No SaaS. No seat pricing. No vendor dashboard. Your logs, your filesystem, your rules.
For GitHub & Slack webhooks, pair it with localtunnel / ngrok / Cloudflare tunnel during development, or put it behind your own reverse proxy.
No DSLs. No visual canvas. No dashboard clicks that vanish into a database you don't own. Workflows live in your repo next to the code they watch.
# sokuza.config.yaml — one file, one source of truth.
server:
port: 24847 # sokuza.ai can auto-detect this port from your browser
integrations:
github:
webhookSecret: ${GITHUB_WEBHOOK_SECRET}
token: ${GITHUB_TOKEN}
slack:
botToken: ${SLACK_BOT_TOKEN}
signingSecret: ${SLACK_SIGNING_SECRET}
workflows:
# ─── One-liner: reuse the built-in AI PR review template ──────────
- name: review-prs
template: ai-pr-review
trigger:
event: pull_request.opened
repo: "my-org/my-repo"
# ─── Custom: review PR, comment, ping Slack ──────────────────────
- name: review-and-notify
trigger:
source: github
event: pull_request.opened
repo: "my-org/my-repo"
branch: main
steps:
- id: diff
action: github-fetch-diff
- id: review
action: ai-review
- action: github-comment
params:
body: "{{steps.review.review}}"
- action: slack-send-message
condition: "{{steps.review.changes_requested}}"
params:
channel: "#code-reviews"
text: "Sokuza flagged {{event.metadata.repo}} PR #{{event.metadata.number}}"
# ─── Agentic: clone, investigate, patch, open follow-up PR ───────
- name: enforce-rules
template: enforce-rules
trigger:
event: pull_request.opened
repo: "my-org/my-repo"
# ─── Scheduled: daily repo health check ──────────────────────────
- name: daily-health
trigger:
source: cron
event: daily
steps:
- id: repo
action: github-clone-repo
params: { repo: "my-org/my-repo" }
- id: analysis
action: ai-agent
params:
workdir: "{{steps.repo.path}}"
prompt: "Audit for vulnerabilities and outdated deps"
- action: slack-send-message
params:
channel: "#engineering"
text: "{{steps.analysis.review}}"
Everything interpolates — {{steps.review.review}}, {{event.metadata.repo}}, {{env.SLACK_CHANNEL}}. Shorthand triggers (repo, branch, labels, author) cover 90% of filters without touching raw payload paths.
Reference any of these by name in your workflow. Copy them out and tweak them. They're all plain YAML, no hidden magic.
Clone + diff + Claude review → GitHub comment or review.
Review a PR, then ping a Slack channel with the verdict.
Agentic rule check: clone, inspect, auto-fix, open a follow-up PR.
Auto-respond to human review comments with targeted fixes.
Deep security scan with prioritized findings.
Architectural audit — dependencies, boundaries, tech debt.
Inspect changed package manifests for risk.
Four-phase project explorer: docs → structure → gaps → briefing.
Read an issue, reproduce, patch, commit, open PR.
Classify, label, and route new issues automatically.
Condense a diff into a human-readable PR summary.
Generate release notes from commit / PR history.
Scheduled daily rollup of repo activity into Slack.
Announce deploys from any webhook source.
Scan diffs for exposed secrets before merge.
Run static analysis and surface only actionable findings.
Close, comment, or nudge stale issues on a schedule.
Parse CI failures, hypothesize causes, post to Slack.
Keep README in sync with your package / CLI surface.
Draft a changelog entry for each merged PR.
Auto-generate API docs from code comments.
Label PRs based on diff heuristics.
Check that new issues include repro / context.
Multi-turn agent that drives a task to completion.
Iterative review → fix → review loop until green.
Pre-merge readiness audit (tests, docs, flags).
Each integration defines the events it emits and the actions it provides. Adding a new one is a single file under src/integrations/.
Same steps on macOS, Linux, and Windows. The full guide covers tunneling, troubleshooting, and how the public site discovers your local instance without seeing any of your data.
# 1. Install (until the npm release lands, clone + link from GitHub) $ git clone https://github.com/<owner>/sokuza.git $ cd sokuza && npm install && npm run build && npm link # 2. Scaffold a config and .env for the integrations you want $ sokuza init # 3. Run it — binds port 24847 (falls back 24848–24852 if busy) $ sokuza # Optional: auto-start on login (macOS / Linux / Windows) $ sokuza install-service
Prerequisites
Example (.env)
# .env
GITHUB_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
SLACK_BOT_TOKEN=xoxb-xxxx-xxxx-xxxx
SLACK_SIGNING_SECRET=xxxxxxxxxxxxxxxx
# Direct API (optional — falls back to Claude Code CLI if unset)
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
No. If ANTHROPIC_API_KEY is unset, the ai-review and ai-agent actions transparently fall back to the Claude Code CLI on your PATH. Install the CLI and run claude login once.
Anywhere Node 20+ runs — your laptop, a home lab, a VPS, a Raspberry Pi. It boots as a single Fastify server on a port you choose.
During development, expose port 24847 with localtunnel, ngrok, or a Cloudflare tunnel and configure that URL as your webhook endpoint. For always-on, put it behind your own reverse proxy.
Only what you tell Claude to look at — usually a diff or a cloned repo. Nothing is sent to Sokuza itself. There is no "Sokuza cloud."
Yes. Actions are just functions that take params + context and return JSON. Register them with engine.registerAction(name, handler) or contribute a new integration under src/integrations/.
No. It complements it. CI runs your tests; Sokuza runs your agents — review, triage, enforcement, investigation — the fuzzy work LLMs are actually good at.