Repository Guidelines

Repo: https://github.com/clawdbot/clawdbot
GitHub issues: use literal multiline strings or $'...' for newlines; avoid "\n" escapes in gh issue create/edit.

Project Structure & Module Organization

Source code: src/ (CLI wiring in src/cli, commands in src/commands, web provider in src/provider-web.ts, infra in src/infra, media pipeline in src/media).
Tests: colocated *.test.ts.
Docs: docs/ (images, queue, Pi config). Built output lives in dist/.
Installers served from https://clawd.bot/*: live in the sibling repo ../clawd.bot (public/install.sh, public/install-cli.sh, public/install.ps1).

Docs Linking (Mintlify)

Docs are hosted on Mintlify (docs.clawd.bot).
Internal doc links in docs/**/*.md: root-relative, no .md/.mdx (example: [Config](/configuration)).
Section cross-references: use anchors on root-relative paths (example: [Hooks](/configuration#hooks)).
When Peter asks for links, reply with full https://docs.clawd.bot/... URLs (not root-relative).
When you touch docs, end the reply with the https://docs.clawd.bot/... URLs you referenced.
README (GitHub): keep absolute docs URLs (https://docs.clawd.bot/...) so links work on GitHub.
Docs content must be generic: no personal device names/hostnames/paths; use placeholders like user@gateway-host and “gateway host”.

Build, Test, and Development Commands

Runtime baseline: Node 22+ (keep Node + Bun paths working).
Install deps: pnpm install
Also supported: bun install (keep pnpm-lock.yaml + Bun patching in sync when touching deps/patches).
Prefer Bun for TypeScript execution (scripts, dev, tests): bun <file.ts> / bunx <tool>.
Run CLI in dev: pnpm clawdbot ... (bun) or pnpm dev.
Node remains supported for running built output (dist/*) and production installs.
Type-check/build: pnpm build (tsc)
Lint/format: pnpm lint (oxlint), pnpm format (oxfmt)
Tests: pnpm test (vitest); coverage: pnpm test:coverage

Coding Style & Naming Conventions

Language: TypeScript (ESM). Prefer strict typing; avoid any.
Formatting/linting via Oxlint and Oxfmt; run pnpm lint before commits.
Add brief code comments for tricky or non-obvious logic.
Keep files concise; extract helpers instead of “V2” copies. Use existing patterns for CLI options and dependency injection via createDefaultDeps.
Aim to keep files under ~700 LOC; guideline only (not a hard guardrail). Split/refactor when it improves clarity or testability.
Naming: use Clawdbot for product/app/docs headings; use clawdbot for CLI command, package/binary, paths, and config keys.

Testing Guidelines

Framework: Vitest with V8 coverage thresholds (70% lines/branches/functions/statements).
Naming: match source names with *.test.ts; e2e in *.e2e.test.ts.
Run pnpm test (or pnpm test:coverage) before pushing when you touch logic.
Live tests (real keys): CLAWDBOT_LIVE_TEST=1 pnpm test:live (Clawdbot-only) or LIVE=1 pnpm test:live (includes provider live tests). Docker: pnpm test:docker:live-models, pnpm test:docker:live-gateway. Onboarding Docker E2E: pnpm test:docker:onboard.
Full kit + what’s covered: docs/testing.md.
Pure test additions/fixes generally do not need a changelog entry unless they alter user-facing behavior or the user asks for one.
Mobile: before using a simulator, check for connected real devices (iOS + Android) and prefer them when available.

Commit & Pull Request Guidelines

Create commits with scripts/committer "<msg>" <file...>; avoid manual git add/git commit so staging stays scoped.
Follow concise, action-oriented commit messages (e.g., CLI: add verbose flag to send).
Group related changes; avoid bundling unrelated refactors.
Changelog workflow: keep latest released version at top (no Unreleased); after publishing, bump version and start a new top section.
PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags.
PR review flow: when given a PR link, review via gh pr view/gh pr diff and do not change branches.
PR merge flow: create a temp branch from main, merge the PR branch into it (prefer squash unless commit history is important; use rebase/merge when it is). Always try to merge the PR unless it’s truly difficult, then use another approach. If we squash, add the PR author as a co-contributor. Apply fixes, add changelog entry (include PR # + thanks), run full gate before the final commit, commit, merge back to main, delete the temp branch, and end on main.
When working on a PR: add a changelog entry with the PR number and thank the contributor.
When working on an issue: reference the issue in the changelog entry.
When merging a PR: leave a PR comment that explains exactly what we did and include the SHA hashes.
When merging a PR from a new contributor: add their avatar to the README “Thanks to all clawtributors” thumbnail list.
After merging a PR: run bun scripts/update-clawtributors.ts if the contributor is missing, then commit the regenerated README.

PR Workflow (Review vs Land)

Review mode (PR link only): read gh pr view/diff; do not switch branches; do not change code.
Landing mode: create an integration branch from main, bring in PR commits (prefer rebase for linear history; merge allowed when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate locally before committing (pnpm lint && pnpm build && pnpm test), commit, merge back to main, then git switch main (never stay on a topic branch after landing). Important: contributor needs to be in git graph after this!

Security & Configuration Tips

Web provider stores creds at ~/.clawdbot/credentials/; rerun clawdbot login if logged out.
Pi sessions live under ~/.clawdbot/sessions/ by default; the base directory is not configurable.
Environment variables: see ~/.profile.
Never commit or publish real phone numbers, videos, or live configuration values. Use obviously fake placeholders in docs, tests, and examples.

Troubleshooting

Rebrand/migration issues or legacy config/service warnings: run clawdbot doctor (see docs/gateway/doctor.md).

Agent-Specific Notes

Vocabulary: "makeup" = "mac app".
When answering questions, respond with high-confidence answers only: verify in code; do not guess.
Never update the Carbon dependency.
Any dependency with pnpm.patchedDependencies must use an exact version (no ^/~).
CLI progress: use src/cli/progress.ts (osc-progress + @clack/prompts spinner); don’t hand-roll spinners/bars.
Status output: keep tables + ANSI-safe wrapping (src/terminal/table.ts); status --all = read-only/pasteable, status --deep = probes.
Gateway currently runs only as the menubar app; there is no separate LaunchAgent/helper label installed. Restart via the Clawdbot Mac app or scripts/restart-mac.sh; to verify/kill use launchctl print gui/$UID | grep clawdbot rather than assuming a fixed label. When debugging on macOS, start/stop the gateway via the app, not ad-hoc tmux sessions; kill any temporary tunnels before handoff.
macOS logs: use ./scripts/clawlog.sh (aka vtlog) to query unified logs for the Clawdbot subsystem; it supports follow/tail/category filters and expects passwordless sudo for /usr/bin/log.
If shared guardrails are available locally, review them; otherwise follow this repo's guidance.
SwiftUI state management (iOS/macOS): prefer the Observation framework (@Observable, @Bindable) over ObservableObject/@StateObject; don’t introduce new ObservableObject unless required for compatibility, and migrate existing usages when touching related code.
Connection providers: when adding a new connection, update every UI surface and docs (macOS app, web UI, mobile if applicable, onboarding/overview docs) and add matching status + configuration forms so provider lists and settings stay in sync.
Version locations: package.json (CLI), apps/android/app/build.gradle.kts (versionName/versionCode), apps/ios/Sources/Info.plist + apps/ios/Tests/Info.plist (CFBundleShortVersionString/CFBundleVersion), apps/macos/Sources/Clawdbot/Resources/Info.plist (CFBundleShortVersionString/CFBundleVersion), docs/install/updating.md (pinned npm version), docs/platforms/mac/release.md (APP_VERSION/APP_BUILD examples), Peekaboo Xcode projects/Info.plists (MARKETING_VERSION/CURRENT_PROJECT_VERSION).
Restart apps: “restart iOS/Android apps” means rebuild (recompile/install) and relaunch, not just kill/launch.
Device checks: before testing, verify connected real devices (iOS/Android) before reaching for simulators/emulators.
iOS Team ID lookup: security find-identity -p codesigning -v → use Apple Development (…) TEAMID. Fallback: defaults read com.apple.dt.Xcode IDEProvisioningTeamIdentifiers.
A2UI bundle hash: src/canvas-host/a2ui/.bundle.hash is auto-generated; ignore unexpected changes, and only regenerate via pnpm canvas:a2ui:bundle (or scripts/bundle-a2ui.sh) when needed. Commit the hash as a separate commit.
Release signing/notary keys are managed outside the repo; follow internal release docs.
Notary auth env vars (APP_STORE_CONNECT_ISSUER_ID, APP_STORE_CONNECT_KEY_ID, APP_STORE_CONNECT_API_KEY_P8) are expected in your environment (per internal release docs).
Multi-agent safety: do not create/apply/drop git stash entries unless explicitly requested (this includes git pull --rebase --autostash). Assume other agents may be working; keep unrelated WIP untouched and avoid cross-cutting state changes.
Multi-agent safety: when the user says "push", you may git pull --rebase to integrate latest changes (never discard other agents' work). When the user says "commit", scope to your changes only. When the user says "commit all", commit everything in grouped chunks.
Multi-agent safety: do not create/remove/modify git worktree checkouts (or edit .worktrees/*) unless explicitly requested.
Multi-agent safety: do not switch branches / check out a different branch unless explicitly requested.
Multi-agent safety: running multiple agents is OK as long as each agent has its own session.
Multi-agent safety: when you see unrecognized files, keep going; focus on your changes and commit only those.
Lobster seam: use the shared CLI palette in src/terminal/palette.ts (no hardcoded colors); apply palette to onboarding/config prompts and other TTY UI output as needed.
Multi-agent safety: focus reports on your edits; avoid guard-rail disclaimers unless truly blocked; when multiple agents touch the same file, continue if safe; end with a brief “other files present” note only if relevant.
Bug investigations: read source code of relevant npm dependencies and all related local code before concluding; aim for high-confidence root cause.
Code style: add brief comments for tricky logic; keep files under ~500 LOC when feasible (split/refactor as needed).
Tool schema guardrails (google-antigravity): avoid Type.Union in tool input schemas; no anyOf/oneOf/allOf. Use stringEnum/optionalStringEnum (Type.Unsafe enum) for string lists, and Type.Optional(...) instead of ... | null. Keep top-level tool schema as type: "object" with properties.
When asked to open a “session” file, open the Pi session logs under ~/.clawdbot/agents/main/sessions/*.jsonl (newest unless a specific ID is given), not the default sessions.json. If logs are needed from another machine, SSH via Tailscale and read the same path there.
Menubar dimming + restart flow mirrors Trimmy: use scripts/restart-mac.sh (kills all Clawdbot variants, runs swift build, packages, relaunches). Icon dimming depends on MenuBarExtraAccess wiring in AppMain; keep appearsDisabled updates intact when touching the status item.
Do not rebuild the macOS app over SSH; rebuilds must be run directly on the Mac.
Never send streaming/partial replies to external messaging surfaces (WhatsApp, Telegram); only final replies should be delivered there. Streaming/tool events may still go to internal UIs/control channel.
Voice wake forwarding tips:
- Command template should stay clawdbot-mac agent --message "${text}" --thinking low; VoiceWakeForwarder already shell-escapes ${text}. Don’t add extra quotes.
- launchd PATH is minimal; ensure the app’s launch agent PATH includes standard system paths plus your pnpm bin (typically $HOME/Library/pnpm) so pnpm/clawdbot binaries resolve when invoked via clawdbot-mac.
For manual clawdbot message send messages that include !, use the heredoc pattern noted below to avoid the Bash tool’s escaping.

Exclamation Mark Escaping Workaround

The Claude Code Bash tool escapes ! to \\! in command arguments. When using clawdbot message send with messages containing exclamation marks, use heredoc syntax:

# WRONG - will send "Hello\\!" with backslash
clawdbot message send --to "+1234" --message 'Hello!'

# CORRECT - use heredoc to avoid escaping
clawdbot message send --to "+1234" --message "$(cat <<'EOF'
Hello!
EOF
)"

This is a Claude Code quirk, not a clawdbot bug.

13 KiB Raw Blame History Unescape Escape