Software Factory Agent Instruction

A developer built a headless agent that polls Basecamp for @mentions on cards, hands the card thread to Claude CLI for processing, and marks notifications as read. The agent runs locally via a systemd user timer every 30 seconds, uses SQLite for deduplication, and requires Claude CLI with --dangerously-skip-permissions for headless operation.

Build a headless agent on this server that polls Basecamp for @mentions on cards, hands the card thread to claude -p , and marks the notification read. Local only, no public webhook. Poll cadence is 30 seconds via a systemd user timer. php systemd user timer every 30s - bc-agent.sh - flock single instance - basecamp notifications --agent filter: type Mention or Assignment, AND app url contains /card tables/cards/ - for each NEW mention dedup via SQLite : - extract card id + bucket id from subscription url - insert SQLite row status='processing' - fetch card + comments: basecamp cards show <id ; basecamp comments list <id - assemble prompt: PROMPT.md workflow instructions + card/thread JSON - cd $WORKDIR && claude -p --dangerously-skip-permissions <PROMPT blocking; runs in the repo; Claude reads thread, acts, and posts back - basecamp notifications read <id mark read - update SQLite status='success' | 'failed' from claude exit code Known values for this install: - Basecamp account id: <your-id - Notification payload shape: top-level .unreads array - Mention object fields used: id , type "Mention" , app url , subscription url subscription url pattern: .../buckets/{BUCKET ID}/recordings/{CARD ID}/subscription.json - The recording id in subscription url is the CARD id not the comment id , which is what basecamp cards show needs. Run each check. All must pass before continuing. Basecamp CLI installed and authenticated as the bot user basecamp --version basecamp auth status basecamp accounts list --agent confirm id 6237538 is present Claude CLI installed and authenticated claude --version GitHub CLI installed and authenticated used to open the PR gh --version gh auth status git identity configured commits are made under this identity git config --get user.name git config --get user.email sqlite3 present command -v sqlite3 || echo "MISSING: install sqlite3" flock present util-linux, normally preinstalled command -v flock || echo "MISSING: install util-linux" Confirm where the tools live needed for PATH in the script which claude basecamp sqlite3 flock gh git Install the compound-engineering plugin into Claude Code one time : claude /plugin marketplace add https://github.com/EveryInc/every-marketplace claude /plugin install compound-engineering Confirm the target repo has a CLAUDE.md at its root. The compound phase reads and updates it every cycle. If the repo has none, create a minimal one before enabling the timer. Critical prerequisite to verify manually: claude -p must run bash, edit files, download attachments, and use git, gh, and basecamp without interactive approval. The agent runs headless, so any permission prompt would hang the run. This install uses --dangerously-skip-permissions as the default see the script and the note below , which removes those prompts. Confirm end to end: claude -p --dangerously-skip-permissions "Run the shell command: basecamp accounts list --agent --account 6237538 and summarize the result." Global state, not tied to any repo. mkdir -p "$HOME/bc-agent" mkdir -p "$HOME/.local/share/bc-agent" mkdir -p "$HOME/.config/bc-agent" sqlite3 "$HOME/.local/share/bc-agent/state.db" "CREATE TABLE IF NOT EXISTS processed mentions notification id TEXT PRIMARY KEY, card id TEXT, bucket id TEXT, status TEXT, -- processing | success | failed created at TEXT DEFAULT datetime 'now' , updated at TEXT ;" Setup agent: stop here and ask the user. This is a one-time value. Prompt them: "What is the absolute path to the project repository this bot should work in? For example /home/jarpis/projects/my-app ." Each claude -p invocation runs with this directory as its working directory, so Claude has the codebase, CLAUDE.md , and project context available whether the mention is a code task or just a question about the thread. Validate the answer before writing it must be an absolute path that exists , then write the config file: Replace with the path the user gave you WORKDIR="/home/jarpis/projects/my-app" Sanity check -d "$WORKDIR" || { echo "Path does not exist: $WORKDIR"; exit 1; } cat "$HOME/.config/bc-agent/config" <<EOF WORKDIR="$WORKDIR" EOF If the path is not a git repo, that is fine, warn the user but proceed. Claude just runs from that directory. Copy the provided PROMPT.md the agent's operating instructions: attachment handling, question vs implementation routing, and the brainstorm to plan to work to review to compound to PR loop to ~/bc-agent/PROMPT.md . The script reads it on every run and appends the live card context before calling Claude. PROMPT.md ships alongside this handover; place it here: cp /path/to/PROMPT.md "$HOME/bc-agent/PROMPT.md" test -f "$HOME/bc-agent/PROMPT.md" && echo "PROMPT.md in place" Create ~/bc-agent/bc-agent.sh . Adjust the PATH line to match which claude basecamp from step 1. bash /usr/bin/env bash set -uo pipefail ---- Config ---- ACCOUNT="your-id" DB="$HOME/.local/share/bc-agent/state.db" LOCK="/tmp/bc-agent.lock" LOG="$HOME/.local/share/bc-agent/agent.log" CONFIG="$HOME/.config/bc-agent/config" systemd user services get a minimal PATH; make tools reachable. export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin:$PATH" ---- Load config sets WORKDIR ---- shellcheck source=/dev/null -f "$CONFIG" && . "$CONFIG" if -z "${WORKDIR:-}" || -d "$WORKDIR" ; then printf '%s WORKDIR unset or missing %s ; edit %s\n' \ "$ date -u +%FT%TZ " "${WORKDIR:-<unset }" "$CONFIG" "$LOG" exit 0 fi ---- Single-instance lock auto-releases on exit, survives crashes ---- exec 9 "$LOCK" flock -n 9 || exit 0 log { printf '%s %s\n' "$ date -u +%FT%TZ " "$ " "$LOG"; } ---- Ensure DB exists idempotent ---- sqlite3 "$DB" "CREATE TABLE IF NOT EXISTS processed mentions notification id TEXT PRIMARY KEY, card id TEXT, bucket id TEXT, status TEXT, created at TEXT DEFAULT datetime 'now' , updated at TEXT ;" ---- Fetch card triggers as TSV: id, subscription url, app url, title ---- Triggers are @mentions or assignments on a card. notifications returns .unreads as null not when the inbox is empty, which is the normal state. .unreads ? yields nothing on null instead of erroring. MENTIONS=$ basecamp notifications --agent --account "$ACCOUNT" --jq ' .unreads ? | select .type == "Mention" or .type == "Assignment" | select .app url | contains "/card tables/cards/" | .id, .subscription url, .app url, .title | @tsv ' || { log "notifications fetch failed"; exit 0; } -z "$MENTIONS" && exit 0 ---- Process each mention here-string keeps the loop in the current shell ---- while IFS=$'\t' read -r NOTIF ID SUB URL APP URL TITLE; do -z "$NOTIF ID" && continue Dedup: skip anything already seen any status SEEN=$ sqlite3 "$DB" "SELECT 1 FROM processed mentions WHERE notification id='$NOTIF ID' LIMIT 1;" -n "$SEEN" && continue Extract IDs from subscription url numeric, safe to interpolate BUCKET ID=$ printf '%s' "$SUB URL" | sed -E 's|. /buckets/ 0-9 + /. |\1|' CARD ID=$ printf '%s' "$SUB URL" | sed -E 's|. /recordings/ 0-9 + /. |\1|' Claim it before doing any work sqlite3 "$DB" "INSERT INTO processed mentions notification id, card id, bucket id, status, updated at VALUES '$NOTIF ID','$CARD ID','$BUCKET ID','processing', datetime 'now' ;" log "processing mention $NOTIF ID card $CARD ID bucket $BUCKET ID :: $TITLE" Fetch the card, then its comment thread. This binary has no --all-comments flag on cards show , and cards show does not include comments inline, so the thread comes from a separate comments list call. CARD=$ basecamp cards show "$CARD ID" --agent --in "$BUCKET ID" --account "$ACCOUNT" 2 "$LOG" COMMENTS=$ basecamp comments list "$CARD ID" --agent --in "$BUCKET ID" --account "$ACCOUNT" 2 "$LOG" if -z "$CARD" ; then log "card fetch failed for $CARD ID" sqlite3 "$DB" "UPDATE processed mentions SET status='failed', updated at=datetime 'now' WHERE notification id='$NOTIF ID';" basecamp notifications read "$NOTIF ID" --account "$ACCOUNT" --agent /dev/null 2 &1 continue fi Assemble the prompt: static instructions PROMPT.md + live card context. PROMPT TEMPLATE=$ cat "$HOME/bc-agent/PROMPT.md" PROMPT=$ cat <<EOF $PROMPT TEMPLATE card id: $CARD ID bucket id: $BUCKET ID account: $ACCOUNT Card JSON: $CARD Comment thread JSON oldest first : $COMMENTS EOF Hand to Claude blocking , running inside the project repo so it has full codebase context. Subshell keeps the cd scoped to this call only. --dangerously-skip-permissions is required: the run is headless and must use bash, file edits, git, gh, and basecamp with no approval prompts. cd "$WORKDIR" && claude -p --dangerously-skip-permissions "$PROMPT" "$LOG" 2 &1 RC=$? Mark read immediately after Claude returns basecamp notifications read "$NOTIF ID" --account "$ACCOUNT" --agent /dev/null 2 &1 Record outcome from Claude's exit code if "$RC" -eq 0 ; then sqlite3 "$DB" "UPDATE processed mentions SET status='success', updated at=datetime 'now' WHERE notification id='$NOTIF ID';" log "success $NOTIF ID" else sqlite3 "$DB" "UPDATE processed mentions SET status='failed', updated at=datetime 'now' WHERE notification id='$NOTIF ID';" log "failed $NOTIF ID rc=$RC" fi done <<< "$MENTIONS" Make it executable: chmod +x "$HOME/bc-agent/bc-agent.sh" Notes on choices already settled: - SQLite is the source of truth for dedup, not Basecamp read status. A row is inserted as processing before any work, so a crash never causes reprocessing. - The --jq filter emits one TSV line per mention. Two mentions on different cards produce two loop iterations, so two separate claude -p runs. flock -n on fd 9 gives single-instance behavior and releases automatically on exit, including crashes, so no stale lockfile. If a run is still busy when the next 30s tick fires, the new run exits immediately and picks up the backlog on the next free tick.- Empty inbox returns .unreads as null , not . The filter uses .unreads ? so this normal state yields empty output and exits quietly rather than erroring every 30 seconds. - Caveat on failure detection: the || { log ...; exit 0; } guard only fires if basecamp notifications exits non-zero. If the CLI ever prints an error envelope but still exits 0 for example on expired auth , a real failure would look like an empty inbox and pass silently. Before trusting this in production, verify what a failed notifications call returns break auth and check the exit code . If it exits 0 on failure, add an explicit check that the output parses and contains an unreads key, and alert on its absence. Use user-level units so they inherit the bot's Basecamp and Claude auth from $HOME . Create ~/.config/systemd/user/bc-agent.service : Unit Description=Basecamp mention agent oneshot After=network-online.target Wants=network-online.target Service Type=oneshot ExecStart=%h/bc-agent/bc-agent.sh Create ~/.config/systemd/user/bc-agent.timer : Unit Description=Run Basecamp mention agent every 30s Timer OnBootSec=30 OnUnitActiveSec=30 AccuracySec=1s Persistent=false Install WantedBy=timers.target AccuracySec=1s matters. The systemd default accuracy is 1 minute, which would smear a 30s cadence. OnUnitActiveSec=30 schedules the next run 30s after the previous run finished. Let user services run without an active login session required on a headless server loginctl enable-linger "$USER" systemctl --user daemon-reload systemctl --user enable --now bc-agent.timer Confirm the timer is scheduled systemctl --user list-timers | grep bc-agent Run once by hand and watch the log ~/bc-agent/bc-agent.sh tail -f ~/.local/share/bc-agent/agent.log Inspect processed rows sqlite3 ~/.local/share/bc-agent/state.db \ "SELECT notification id, card id, status, updated at FROM processed mentions ORDER BY created at DESC LIMIT 10;" Watch systemd execution journalctl --user -u bc-agent.service -f End-to-end check: @mention the bot user in a card comment, wait up to ~30s, confirm a reply comment appears and a success row lands in SQLite. Retry a stuck or failed item manually: Find failures sqlite3 ~/.local/share/bc-agent/state.db "SELECT FROM processed mentions WHERE status='failed';" Force reprocessing of one notification delete its row; it must still be unread in Basecamp sqlite3 ~/.local/share/bc-agent/state.db "DELETE FROM processed mentions WHERE notification id='<ID ';" - Posting model settled: agentic . Claude posts its own reply and takes actions branches, commits, PR via the tools it runs. This requires headless tool use, enabled here with --dangerously-skip-permissions . Git is the safety net: work happens on a bc/<slug branch, never on main . - PR timing settled: PR last . Work commits and pushes to the feature branch but opens no PR. Review runs on the branch diff, then compound documents, then the PR is opened as the final step. This reorders the compound-engineering plugin's native flow which opens the PR during work . To use the native flow instead, have Claude open the PR at the end of work and run review against the PR. - Execution model. claude -p runs blocking, so mentions in one tick are processed sequentially and a long autonomous run work plus review plus compound holds the lock. That is expected and safe: other mentions wait and are picked up on the next free tick. A shared repo working directory makes concurrent runs unsafe anyway two Claudes editing the same tree , so blocking is the right default here. - Failure visibility. failed rows are recorded but nothing alerts you. Consider a daily check that greps for status='failed' and pings you Basecamp chat post, email, etc. . - Run duration. The post-approval run can take many minutes review spawns many agents . There is no wall-clock limit in the script; the lock simply stays held. If you later want a ceiling, wrap the Claude call in timeout <seconds and treat a timeout as a failed row.