115 lines
11 KiB
Markdown
115 lines
11 KiB
Markdown
# Repository Guidelines
|
||
|
||
## 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/`.
|
||
|
||
## 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)`).
|
||
- README (GitHub): keep absolute docs URLs (`https://docs.clawd.bot/...`) so links work on GitHub.
|
||
|
||
## 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` (biome check), `pnpm format` (biome format)
|
||
- Tests: `pnpm test` (vitest); coverage: `pnpm test:coverage`
|
||
|
||
## Coding Style & Naming Conventions
|
||
- Language: TypeScript (ESM). Prefer strict typing; avoid `any`.
|
||
- Formatting/linting via Biome; 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.
|
||
- 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.
|
||
- 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.
|
||
- 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 (Clawdis → Clawdbot) 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.
|
||
- 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).
|
||
- 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:
|
||
|
||
```bash
|
||
# 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.
|