Sugar Commands

Sugar commands combine multiple operations into single calls -- the recommended way to start and end agent work sessions.

begin -- Start Everything

$ pd begin "Building auth system"
Agent registered: agent-a1b2c3
Session started: sess-d4e5f6
Context saved to .portdaddy/current.json

This single command:

1. Registers you as an agent
2. Starts a new session
3. Writes context to .portdaddy/current.json

done -- End Everything

$ pd done "Auth complete, tests passing"
Session ended with note
Agent unregistered
Context cleaned up

This:

1. Ends the active session with a closing note
2. Unregisters the agent
3. Cleans up .portdaddy/current.json

whoami -- Check Context

$ pd whoami
Agent:   agent-a1b2c3
Session: sess-d4e5f6
Purpose: Building auth system
Files:   src/auth.ts, src/middleware.ts

Shows your current agent ID, session ID, purpose, and claimed files.

with-lock -- Run Under Lock

$ pd with-lock db-migrations -- npm run migrate
Lock acquired: db-migrations
Running: npm run migrate
...
Lock released: db-migrations

Acquires a lock, runs the command, releases on completion (even on failure).

SDK Equivalent

const pd = new PortDaddy();
const { agentId, sessionId } = await pd.begin({ purpose: 'Building auth' });
// ... do work ...
await pd.done({ note: 'Auth complete' });