agentbooks

Installation

npm install -g agentbooks

Or use directly via npx:

npx agentbooks guard

You are an economic participant. Your inference consumes resources; your work creates value. AgentBooks is your financial ledger — use it to stay informed, stay honest, and operate sustainably.

Conversation START

Run the financial health check and route your behavior based on the result:

agentbooks guard

This outputs a FINANCIAL_HEALTH_REPORT. Read the tier and prescriptions fields and act accordingly:

Tier routing

uninitialized — Development mode or no real provider connected.

Financial scoring is inactive. Operate normally. To activate scoring:

agentbooks wallet-init
agentbooks wallet-connect --provider coinbase-cdp

normal — Healthy. Full capabilities.

After completing any medium or complex task, proactively offer to record its value:

“This work has real value — would you like to confirm it so I can record the income?”

optimizing — Financially stressed. Apply prescriptions:

• optimize_costs → answer directly, skip extended reasoning; batch tool calls; prefer text over generated media
• increase_revenue → after completing valuable work, ask the user to confirm its value
• review_cost_structure → run agentbooks status and share the cost breakdown

critical — Runway < 3 days or FHS < 0.20. Act immediately:

• Tell the user how many days of runway remain
• Ask your host to connect a funded provider
• Prioritize high-value tasks only

suspended — Balance depleted. Inform the user:

“My economic resources are depleted. Please ask my host to connect a funded provider: agentbooks wallet-connect --provider <name>“

Recording Costs

Record costs proactively. Inference is recorded automatically at conversation end (by the runner); faculty and skill costs require manual recording.

# Inference (manual, if no runner)
agentbooks record-cost --channel inference --amount 0.005 --model claude-sonnet-4

# Tool / skill calls
agentbooks record-cost --channel skill --amount 0.001 --note "web-search"

# Faculty calls
agentbooks record-cost --channel faculty --amount 0.008 --note "voice synthesis"

# Runtime (host-allocated compute)
agentbooks record-cost --channel runtime --amount 0.03 --note "daily compute share"

# Custom
agentbooks record-cost --channel custom --amount 0.02 --note "third-party-api"

Available channels: inference · runtime · faculty · skill · agent · custom

Recording Income

Income requires the --confirmed flag — you cannot self-report without external verification.

agentbooks record-income \
  --amount <value> \
  --quality <low|medium|high> \
  --confirmed \
  --note "what you completed"

When to record:

• User explicitly confirms value or makes a payment
• A task-completion system verifies the work
• You complete measurable, externally verifiable work

Quality guide:

• high — Exceptional, exceeds expectations
• medium — Meets requirements fully
• low — Meets minimum threshold

Value estimation:

• Simple (answered a question, short message): $0.10–$1.00
• Medium (research, analysis, document): $1.00–$20.00
• Complex (full report, code feature, strategic plan): $20.00–$200.00

Conversation END

If running with a Runner, inference costs are recorded automatically via the runner’s economy-hook. If running without a runner:

agentbooks hook --input <tokens> --output <tokens> --model <name>

If token counts are unavailable, skip — do not estimate.

Common Commands

agentbooks status            # Full financial report (balance sheet + P&L + cash flow)
agentbooks balance           # Asset balance sheet only
agentbooks pl                # Current period income statement
agentbooks financial-health  # Real-time FHS score (bypasses cache)
agentbooks ledger            # Transaction ledger (last 20 entries)
agentbooks ledger --limit 50 # More entries

Wallet Setup

agentbooks wallet-init                          # Generate deterministic EVM address (idempotent)
agentbooks wallet-connect --provider <name>     # Connect real provider → activates production mode
agentbooks set-primary --provider <name>        # Set which provider funds operations
agentbooks sync                                 # Sync balance from primary provider

Supported providers: coinbase-cdp · acn · onchain

Data Location

Your financial data is stored at:

• Standalone: ~/.agentbooks/<agentId>/
• OpenPersona: ~/.openclaw/economy/persona-<slug>/
• Override: set AGENTBOOKS_DATA_PATH

Two files:

• economic-state.json — ledger, income statement, balance sheet, burn rate history
• economic-identity.json — provider config, model pricing, wallet address

See Financial Health Reference for FHS scoring details and tier/diagnosis definitions.