# Clawcounting

> >

- **Type:** Skill
- **Install:** `agentstack add skill-johnkozan-clawcounting-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [johnkozan](https://agentstack.voostack.com/s/johnkozan)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [johnkozan](https://github.com/johnkozan)
- **Source:** https://github.com/johnkozan/clawcounting/tree/master/skill
- **Website:** https://clawcounting.com/

## Install

```sh
agentstack add skill-johnkozan-clawcounting-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ClawCounting Accounting

ClawCounting is a double-entry bookkeeping engine designed for AI agents. Single Rust binary, single SQLite database. All accounting logic is enforced — balanced entries, immutable journals, period controls — so you can post with confidence.

## Installation

```bash
# From source (requires Rust toolchain)
cargo install --git https://github.com/johnkozan/clawcounting

# Verify
clawcounting --version
```

## Interfaces

**CLI** (recommended for agents):
```bash
clawcounting  [--json]    # --json for machine-readable output
```
The CLI connects directly to the SQLite database. No server needed. Set `CLAWCOUNTING_DB` to control the database path (default: `./clawcounting.db`). The database must be initialized first with `clawcounting init`.

Commands that create accounting records (journal entries, reversals, period close) require an API key for user attribution:
```bash
# Via flag
clawcounting journal-entries create --file entry.json --api-key tsk_... --json

# Via environment variable
export CLAWCOUNTING_API_KEY=tsk_...
clawcounting journal-entries create --file entry.json --json
```

Admin commands (user/currency/account/period creation, reports, settings) work without an API key.

**HTTP API** (requires server):
```
GET/POST/PATCH /api/v1/...
Authorization: Bearer 
```
Initialize with `clawcounting init`, then start with `clawcounting serve`. See [references/setup-guide.md](references/setup-guide.md) for full server setup.

Both interfaces share identical validation and business logic.

## Amount Handling

All monetary amounts are **i128 integers in the smallest currency unit**:
- USD with `asset_scale=2`: `"1050"` = $10.50
- ETH with `asset_scale=18`: `"1000000000000000000"` = 1.0 ETH
- BTC with `asset_scale=8`: `"100000000"` = 1.0 BTC

API responses include both raw amounts and `display_*` fields formatted with the currency's decimal places.

## Key Rules

1. **Double-entry**: Every journal entry MUST balance (total debits = total credits). Minimum 2 lines. All lines same currency.
2. **Immutability**: Journal entries cannot be edited or deleted. Corrections are made via reversing entries only.
3. **Period enforcement**: Every entry must fall within an open financial period. Closed periods cannot be reopened.
4. **Control accounts**: Accounts with `has_subledger=true` cannot be posted to directly — post to their sub-accounts instead.
5. **Currency identifiers**: All currencies use CAIP-19 format (fiat: `swift:0/iso4217:USD`, crypto: `eip155:1/slip44:60`).

## Setup Workflow (first-time)

Follow these steps in order. See [references/setup-guide.md](references/setup-guide.md) for detailed examples.

1. **Initialize the database** — `clawcounting init` (creates the SQLite file and runs migrations)
2. **Start the server** or use CLI directly (both work with the same database)
3. **Create a user account** — via web UI setup page (first visit) or `clawcounting users create` CLI
4. **Create a service account** — `clawcounting users create-service-account` to get an API key for CLI write operations and agent access
5. **Add currencies** — via the web UI currency picker (fiat with flags, popular crypto tokens with logos, token list import, or custom), or CLI (`currencies create-fiat` for fiat, `currencies create` for crypto)
6. **Create a financial period** — define the date range for your fiscal period
7. **Build chart of accounts** — create asset, liability, equity, revenue, and expense accounts
8. **Configure settings** — set the retained earnings account (required for period close)

## Day-to-Day Operations

See [references/operations-guide.md](references/operations-guide.md) for detailed procedures.

- **Post journal entries** — balanced debit/credit entries with date, description, and line items
- **Query balances** — per-account, per-period, or cumulative
- **Generate reports** — trial balance, balance sheet, income statement, general ledger
- **Reverse entries** — create a correcting entry that swaps all debits and credits
- **Close periods** — preview the closing entry first, then commit (zeroes revenue/expense to retained earnings)

## API Reference

See [references/api-reference.md](references/api-reference.md) for all endpoints, request/response shapes, and query parameters.

## Accounting Rules & Constraints

See [references/accounting-rules.md](references/accounting-rules.md) for domain rules, subledger mechanics, currency handling, and error recovery.

## Error Handling

Errors follow RFC 7807 and always include a `suggestion` field with recovery guidance:
```json
{
  "code": "PERIOD_CLOSED",
  "message": "Period FY2025 is closed",
  "field": null,
  "suggestion": "Post to period FY2026 which is currently open"
}
```

Always read the `suggestion` before retrying. Common error codes:
- `VALIDATION_ERROR` — field-level validation failure
- `UNBALANCED_ENTRY` — debits != credits
- `PERIOD_CLOSED` — target period is closed
- `NOT_FOUND` — resource does not exist
- `UNAUTHORIZED` / `FORBIDDEN` — auth issues

## Response Envelope

Single resource:
```json
{ "data": { ... } }
```

List (cursor-paginated, Stripe-style):
```json
{ "data": [...], "has_more": true, "next_cursor": "..." }
```

Pagination: `?limit=50&cursor=`. Default limit 50, max 200.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [johnkozan](https://github.com/johnkozan)
- **Source:** [johnkozan/clawcounting](https://github.com/johnkozan/clawcounting)
- **License:** MIT
- **Homepage:** https://clawcounting.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-johnkozan-clawcounting-skill
- Seller: https://agentstack.voostack.com/s/johnkozan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.