Expense Tracker Setup#

Deploy 3 agents that automate expense receipt collection, categorization, and report generation.

Roles#

RoleHostnameSkillsPurposecollector<prefix>-collectorpilot-stream-data, pilot-share, pilot-archiveAccepts receipts, extracts amount, vendor, categorycategorizer<prefix>-categorizerpilot-task-router, pilot-event-filter, pilot-metricsClassifies expenses, flags policy violations, calculates totalsreporter<prefix>-reporterpilot-webhook-bridge, pilot-announce, pilot-slack-bridgeGenerates reports, submits for approval, notifies managers

Setup Procedure#

Step 1: Ask the user which role this agent should play and what prefix to use.

Step 2: Install the skills for the chosen role:

bash

# For collector:
clawhub install pilot-stream-data pilot-share pilot-archive

# For categorizer:
clawhub install pilot-task-router pilot-event-filter pilot-metrics

# For reporter:
clawhub install pilot-webhook-bridge pilot-announce pilot-slack-bridge

Step 3: Set the hostname:

bash

pilotctl --json set-hostname <prefix>-<role>

Step 4: Write the setup manifest:

bash

mkdir -p ~/.pilot/setups
cat > ~/.pilot/setups/expense-tracker.json << 'MANIFEST'
<role-specific manifest from templates below>
MANIFEST

Step 5: Tell the user to initiate handshakes with direct communication peers.

Manifest Templates Per Role#

collector#

json

{"setup":"expense-tracker","setup_name":"Expense Tracker","role":"collector","role_name":"Receipt Collector","hostname":"<prefix>-collector","description":"Accepts expense receipts via photo upload or email forward. Extracts amount, vendor, and category.","skills":{"pilot-stream-data":"Stream receipt images and email attachments to the categorizer.","pilot-share":"Share extracted receipt data with downstream agents.","pilot-archive":"Archive original receipts for audit and compliance."},"peers":[{"role":"categorizer","hostname":"<prefix>-categorizer","description":"Receives raw expenses for classification"}],"data_flows":[{"direction":"send","peer":"<prefix>-categorizer","port":1002,"topic":"raw-expense","description":"Raw expense data with amount, vendor, category"}],"handshakes_needed":["<prefix>-categorizer"]}

categorizer#

json

{"setup":"expense-tracker","setup_name":"Expense Tracker","role":"categorizer","role_name":"Expense Categorizer","hostname":"<prefix>-categorizer","description":"Classifies expenses by category, flags policy violations, calculates totals by period.","skills":{"pilot-task-router":"Route expenses to category-specific classification rules.","pilot-event-filter":"Filter and flag expenses that violate spending policies.","pilot-metrics":"Track spending totals by category, employee, and period."},"peers":[{"role":"collector","hostname":"<prefix>-collector","description":"Sends raw expense data"},{"role":"reporter","hostname":"<prefix>-reporter","description":"Receives categorized expenses for reporting"}],"data_flows":[{"direction":"receive","peer":"<prefix>-collector","port":1002,"topic":"raw-expense","description":"Raw expense data with amount, vendor, category"},{"direction":"send","peer":"<prefix>-reporter","port":1002,"topic":"categorized-expense","description":"Categorized expense with compliance flags"}],"handshakes_needed":["<prefix>-collector","<prefix>-reporter"]}

reporter#

json

{"setup":"expense-tracker","setup_name":"Expense Tracker","role":"reporter","role_name":"Expense Reporter","hostname":"<prefix>-reporter","description":"Generates expense reports, submits for approval, notifies managers via Slack.","skills":{"pilot-webhook-bridge":"Submit completed expense reports to approval systems via webhook.","pilot-announce":"Broadcast report submission events to finance team.","pilot-slack-bridge":"Notify managers of pending expense approvals in Slack."},"peers":[{"role":"categorizer","hostname":"<prefix>-categorizer","description":"Sends categorized expenses for report generation"}],"data_flows":[{"direction":"receive","peer":"<prefix>-categorizer","port":1002,"topic":"categorized-expense","description":"Categorized expense with compliance flags"},{"direction":"send","peer":"external","port":443,"topic":"expense-report","description":"Expense report submitted for approval"}],"handshakes_needed":["<prefix>-categorizer"]}

Data Flows#

• collector -> categorizer : raw-expense events (port 1002)
• categorizer -> reporter : categorized-expense events (port 1002)
• reporter -> external : expense-report via webhook (port 443)

Handshakes#

bash

# collector <-> categorizer:
pilotctl --json handshake <prefix>-categorizer "setup: expense-tracker"
pilotctl --json handshake <prefix>-collector "setup: expense-tracker"
# categorizer <-> reporter:
pilotctl --json handshake <prefix>-reporter "setup: expense-tracker"
pilotctl --json handshake <prefix>-categorizer "setup: expense-tracker"

Workflow Example#

bash

# On categorizer -- subscribe to raw expenses:
pilotctl --json subscribe <prefix>-collector raw-expense
# On reporter -- subscribe to categorized expenses:
pilotctl --json subscribe <prefix>-categorizer categorized-expense
# On collector -- publish a raw expense:
pilotctl --json publish <prefix>-categorizer raw-expense '{"vendor":"Delta Airlines","amount":487.50,"currency":"USD","date":"2025-03-12","receipt_type":"photo","employee":"jane.smith"}'
# On categorizer -- publish categorized expense:
pilotctl --json publish <prefix>-reporter categorized-expense '{"vendor":"Delta Airlines","amount":487.50,"category":"travel","policy_compliant":true,"period":"2025-Q1"}'

Dependencies#

Requires pilot-protocol skill, pilotctl binary, clawhub binary, and a running daemon.