Metadata-Version: 2.4
Name: credex-claudecode
Version: 0.1.4
Summary: Audit chain for Claude Code workflows — consensus verification, persistent memory, and XRPL provenance for every agent action.
Project-URL: Homepage, https://credexai.live
Project-URL: Documentation, https://credexai.live/docs/universal-connector.html
Project-URL: Repository, https://github.com/credexai-labs/credex-claudecode
Project-URL: Issues, https://github.com/credexai-labs/credex-claudecode/issues
Author-email: CredEx AI <hello@credexai.live>
License-Expression: MIT
Keywords: ai-agents,audit,claude-code,credex,mcp,verification,xrpl
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# credex-claudecode

> **$60 to prove what $500 bought you.**

Audit chain for Claude Code workflows — consensus verification, persistent memory, and XRPL provenance for every agent action.

When Claude Code spins up hundreds of parallel agents that run for *days*, nobody can reconstruct what happened without a verification trail. `credex-claudecode` is that trail.

## What It Does

```
credex run "Migrate from Express to FastAPI" --verify milestones
```

1. **Wraps Claude Code** — runs your prompt through `claude -p` with streaming output
2. **Parses every action** — tool calls, file writes, bash commands, agent decisions
3. **Routes through CredEx verification** — pre-verification at $0.001/action, full 5-LLM consensus at $0.10/milestone
4. **Anchors to XRPL** — cryptographic provenance at workflow boundaries
5. **Produces `workflow.audit.json`** — third-party verifiable record of everything

## Cost

For a typical Claude Code "ultracode" workflow ($500 in tokens, ~45,000 actions):

| Tier | What | Cost |
|------|------|------|
| Pre-verification | Every action, cheap model | $0.001 × 45,000 = $45 |
| Full consensus | 5-LLM panel at milestones | $0.10 × 50 = $5 |
| XRPL anchoring | Workflow boundaries | ~$10 |
| **Total** | | **~$60 (12% overhead)** |

## Install

```bash
pip install credex-claudecode
```

Requires:
- Python 3.10+
- Claude Code CLI (`npm install -g @anthropic-ai/claude-code`)
- CredEx API key (optional for dry-run mode)

## Quick Start

### Get a CredEx API key

```bash
# Instant anonymous key
curl -X POST https://credexai.live/agent/auth -d '{"type":"anonymous"}'

# Set it
export CREDEX_API_KEY=credex_...
```

### Run a workflow with audit chain

```bash
# Full audit (milestones verified + XRPL anchored)
credex run "Migrate the auth module from Express to FastAPI"

# Verify everything (costs more, thorough)
credex run "Security audit of the payment module" --verify all

# Dry run (no CredEx, local audit only)
credex run "Rewrite tests in pytest" --dry-run

# Pass Claude Code options
credex run "Fix the bug in auth.py" --allowed-tools "Read,Edit,Bash" --model claude-sonnet-4-20250514
```

### Inspect an audit

```bash
# Pretty-print summary
credex audit workflow.audit.json

# Verify chain integrity
credex audit workflow.audit.json --verify
```

### Lightweight hooks (no wrapper needed)

```bash
# Install PostToolUse hooks into your project
credex install-hooks

# Now every Claude Code session automatically logs to CredEx
claude  # Use normally — CredEx logging happens in background
```

## `workflow.audit.json`

The audit file is a self-contained, third-party verifiable record:

```json
{
  "version": "1.0.0",
  "generator": "credex-claudecode",
  "document_hash": "a1b2c3...",
  
  "workflow": {
    "session_id": "session_abc123",
    "prompt": "Migrate from Express to FastAPI",
    "started_at": "2025-05-29T01:00:00Z",
    "ended_at": "2025-05-29T01:45:00Z",
    "claude_cost_usd": 12.50,
    "total_tokens": 2500000,
    "total_turns": 47
  },
  
  "summary": {
    "total_actions": 342,
    "total_milestones": 28,
    "files_modified": ["src/main.py", "src/routes/auth.py", "..."],
    "credex_verification": {
      "total_verifications": 28,
      "total_cost_usd": 2.85,
      "verdicts": {"TRUE": 26, "MIXED": 2},
      "anchors": 3
    }
  },
  
  "action_chain": [
    {
      "id": "tool-abc123",
      "sequence_number": 1,
      "action_type": "tool_use",
      "tool_name": "Read",
      "content_hash": "f4a3...",
      "chain_hash": "b7c2...",
      "prev_hash": "genesis"
    }
  ],
  
  "chain_proof": {
    "genesis_hash": "genesis",
    "final_hash": "d8e9...",
    "chain_length": 342,
    "algorithm": "sha256-linked"
  }
}
```

**Verification**: Each action's `chain_hash = SHA256(prev_hash + content_hash + sequence)`. Recompute from genesis to verify the entire chain.

## Architecture

```
┌──────────────────────────────────────────────┐
│ credex run "prompt"                          │
├──────────────────────────────────────────────┤
│                                              │
│  Claude Code CLI (subprocess)                │
│  --output-format stream-json                 │
│  │                                           │
│  ▼                                           │
│  StreamEventParser                           │
│  ├─ tool_use events → ParsedAction           │
│  ├─ tool_result events → ParsedAction        │
│  └─ result event → WorkflowSession           │
│     │                                        │
│     ▼                                        │
│  CredExVerifier                              │
│  ├─ Pre-verify: $0.001 (cheap, every action) │
│  ├─ Consensus: $0.10 (5-LLM, milestones)    │
│  └─ Anchor: XRPL (workflow boundaries)       │
│     │                                        │
│     ▼                                        │
│  AuditChainGenerator                         │
│  └─ workflow.audit.json                      │
│                                              │
└──────────────────────────────────────────────┘
```

## Integration Paths

### 1. CLI Wrapper (Full Audit)
Use `credex run` for complete audit chains. Best for high-stakes workflows: migrations, security audits, rewrites.

### 2. PostToolUse Hooks (Lightweight)
Use `credex install-hooks` for background logging. Best for everyday use — zero friction, events stored in CredEx memory.

### 3. Python SDK (Programmatic)
```python
from credex_claudecode.parser import StreamEventParser
from credex_claudecode.verifier import CredExVerifier

parser = StreamEventParser(prompt="my workflow")
verifier = CredExVerifier(api_key="credex_...", verify_level="milestones")

# Parse events from any source
for line in event_stream:
    actions = parser.parse_line(line)
    for action in actions:
        result = await verifier.process_action(action)

session = parser.finalize()
```

## Why This Matters

Claude Code "ultracode" workflows spin up ~200 parallel agents, execute ~45,000 actions, and run for *days*. When that $500 workflow completes:

- **Without CredEx**: You have code changes. You don't know what decisions were made, what was tried and failed, or what was verified vs. guessed.
- **With CredEx**: You have a cryptographic audit chain. Every action verified, every decision anchored, every workflow reconstructable.

For enterprise teams running Claude Code on production codebases, the audit chain isn't optional — it's the difference between "we think the migration worked" and "here's the proof."

## Links

- **CredEx AI**: [credexai.live](https://credexai.live)
- **MCP Tools**: [credexai.live/.well-known/mcp.json](https://credexai.live/.well-known/mcp.json)
- **Connector Docs**: [credexai.live/docs/universal-connector.html](https://credexai.live/docs/universal-connector.html)
- **API Auth**: [credexai.live/auth.md](https://credexai.live/auth.md)

## License

MIT
