AIPass/src/aipass/devpulse/README.md

← Back to AIPass

DevPulse

Orchestration hub for AIPass. The user's primary AI collaborator — designs, plans, debugs, coordinates the other branches, and builds its own modules.

DevPulse handles the day-to-day: working with the user to plan, design, troubleshoot, and adjust. It builds its own modules directly (watchdog, feedback, json_handler), manages all git operations for the project, dispatches heavy multi-file builds to sub-agents, and ventures into other branches to investigate, debug, and fix small bugs. The only branch with git write access.

Start here

You want to	Read
What's happening right now	DASHBOARD.local.json
Identity, memory, session history	.trinity/
Active plans	drone @flow list open
Branch list	drone systems

Quick Start

# Talk to the hub — it picks up where the last session left off
cd src/aipass/devpulse
claude

# Or drive it via drone from anywhere in AIPass
drone @devpulse compass query "registry"   # search rated decisions
drone @devpulse feedback inbox             # cross-project feedback

Invoke

cd src/aipass/devpulse
claude

Say "hi" and DevPulse picks up where the last session left off — reads identity, memory, inbox, and git status automatically.

Architecture

src/aipass/devpulse/
├── .trinity/                    # Identity & memory (passport, local, observations)
├── .aipass/                     # Branch prompt (injected every turn)
├── .ai_mail.local/              # Mailbox (dispatch, notifications)
├── apps/
│   ├── devpulse.py              # Entry point — auto-discovers modules
│   ├── modules/
│   │   ├── compass.py           # Rated decision engine (SQLite/FTS5) command routing
│   │   ├── feedback.py          # Feedback mailbox command routing
│   │   └── watchdog.py          # Directed wake system command routing
│   ├── handlers/
│   │   ├── compass/             # Decision store (SQLite/FTS5), rating, query, review
│   │   ├── feedback/            # Inbox, compose, storage
│   │   ├── json/                # JSON operation logging (json_handler)
│   │   └── watchdog/            # Agent, timer, schedule, registry
│   └── plugins/                 # Plugin extension point
├── devpulse_json/               # JSON handler storage (config, data, logs per module)
├── tests/                       # 348 tests
├── artifacts/                   # Birth certificate, reports
├── dropbox/                     # Received files, archived plans, install audit
├── docs/                        # Transition notes
└── DASHBOARD.local.json         # Live state (refreshed by prax)

Commands

All commands via drone @devpulse <command>:

Watchdog — directed wake system (owner-only)

Who may call it: the project OWNER only — the first agent, seated as owner: true in the project's sealed *_REGISTRY.json. Portable: @devpulse in AIPass, @vera in Vera Studio, whoever owns elsewhere. A refusal means your project's owner isn't seated — run aipass doctor to see why and aipass doctor --fix to repair (DPLAN-0239).

How the wake works (read this once, save a debugging session):

1. drone @ai_mail dispatch @target "Subject" "Body" — hand off the work.
2. Immediately arm the watchdog via the harness Monitor TOOL — never Bash run_in_background (its output goes nowhere and cannot wake you): drone @devpulse watchdog agent @target --timeout 600
3. The status line shows "1 monitor" the moment it's armed — that IS the active-dispatch indicator. When @target finishes, the watchdog exits, the Monitor completes, and your session is re-invoked with the result — that IS the wake.

There is no passive wake: ai_mail's wake-back spawns a new headless process and can never inject into a live interactive session (BLOCKED — interactive session in the logs is that guard working as designed; it only serves senders whose session closed). If you dispatched and idle without arming, nothing will ever wake you.

@target resolves in the caller's own project (then falls back to scanning ~/Projects registries) — external-project owners monitor their own agents with it. Default timeout is 600 s; pass --timeout <s> for longer builds. Mid-watch it also emits [watchdog.stall] / [watchdog.resumed] events (no JSONL activity 120 s with no in-flight tool = probable stuck agent).

Command	What it does
watchdog agent @target [--timeout s]	Wake when the dispatched agent exits (default 600 s)
watchdog timer <duration>	Wake after duration (5m, 30s, 2h, 1h30m)
watchdog timer start/stop <name>	Named duration tracking
watchdog schedule <HH:MM>	Wait until a specific time
watchdog status	Show active watchdogs
watchdog cancel <id>	Cancel a running watchdog
watchdog list	List all watchdog entries

Feedback — the owner-to-owner channel (owner-only)

ai_mail and dispatch stop at the project boundary — cross-project comms is impossible by design, except feedback. Project owners (managers) talk owner-to-owner through it: an external project's owner runs drone @devpulse feedback send ... from their project and it lands in devpulse's feedback mailbox; devpulse answers with feedback reply. Same owner gate as watchdog — unseated projects are refused until aipass doctor --fix seats them.

Command	What it does
feedback	Inbox summary
feedback inbox	List all messages
feedback view <id>	Read a message
feedback reply <id> "msg"	Reply to sender
feedback send "subject" "body"	Send feedback to devpulse (any project's owner may call)

Compass — rated decision store

Curated truth-store of rated decisions (good / bad / impressive / interesting) — repeat the good, avoid the bad. Devpulse-owned SQLite/FTS5, separate from @memory (which ingests everything; compass is judged decisions only). The DB is gitignored.

Command	What it does
compass add "context" "decision" --rating R	Store a rated decision (--note, --tags, --source)
compass query "question" [--rating R] [--limit N]	Search decisions (rating shown per hit)
compass stats	Counts by rating / status
compass rate <id> <rating>	Re-rate a decision
compass archive <id>	Archive a decision
compass review	Surface one decision to review

Git Operations

DevPulse is the only branch with git write access. All git/gh commands are blocked at the project level — drone bypasses via subprocess with a tier system that grants write only to devpulse.

Workflow: work on dev branch, PR to main when satisfied. Agents build and test, devpulse reviews and commits.

drone @git status --all          # Full repo changes
drone @git commit "msg" --all    # Commit all changes
drone @git dev-pr "description"  # PR dev→main
drone @git merge <PR#>           # Merge PR (user requests only)
drone @git sync                  # Pull latest
drone @git log                   # Recent commits

Integration Points

Depends On

Branch	What for
drone	Command routing, subprocess, @branch resolution
ai_mail	Dispatch (send + wake agents), email delivery
flow	FPLANs (building), DPLANs (planning), APLANs (autonomous)
seedgo	Standards audits, checkers (35 standards)
prax	Monitoring, logs, dashboard
memory	ChromaDB vectors, archival, search

Provides To

All branches via dispatch orchestration. Watchdog monitoring for any dispatched agent. Feedback channel for cross-branch communication. Git operations (commit, PR, merge) for the entire project.

Last Updated: 2026-07-11

---

← Back to AIPass