---
_akf: '{"v":"1.0","claims":[{"c":"Trust metadata for README.md","t":0.7,"id":"1979cbeb","src":"unspecified","tier":5,"ver":false,"ai":true,"evidence":[{"type":"other","detail":"updated certify and github action references","at":"2026-03-18T04:21:48.869226+00:00"}]}],"id":"akf-c33254656fc5","agent":"claude-code","at":"2026-03-18T04:21:48.870623+00:00","label":"public","inherit":true,"ext":false,"sv":"1.1"}'
---
AKF — The AI Native File Format
A stamp costs ~15 tokens. Re-verifying costs 15,000.
Think EXIF for AI — trust metadata that travels with every AI-generated file,
so the next agent (or human) knows what it can build on.
⭐ Star on GitHub ·
Website ·
🛡️ Is This AI-Generated? ·
🇪🇺 Compliance Check ·
📊 Repo Scanner
Quickstart ·
AI Agents ·
MCP Server ·
Agent Skills ·
CLI ·
Website
---
## Paste this to your agent
Don't install AKF yourself — let your agent do it. Paste this into Claude Code, Cursor, OpenClaw, or any coding agent:
```
Install AKF (pip install akf, or pipx install akf) and set it up: run `akf init --git-hooks`.
From now on:
- After you create or modify a file, stamp it:
akf stamp --agent --evidence ""
- Before building on any existing file, check it first:
akf check
OK = fresh stamp with verified evidence, skip re-verification. STALE/LOW/UNSTAMPED = verify before trusting.
If you support MCP, also register the server: {"mcpServers":{"akf":{"command":"python","args":["-m","mcp_server_akf"]}}}
```
Your agent installs its own provenance layer — and every file it touches carries trust metadata from then on.
## Why agents need this
Agents redo work constantly: re-read files, re-run tests, re-derive conclusions — because nothing tells them what was already verified. A stamp is cached verification state:
```console
# Session 1 — agent fixes auth, tests pass
$ akf stamp auth.py --agent claude-code --evidence "42/42 tests passed"
# Session 2 — tomorrow, any agent, any tool
$ akf check auth.py
OK trust=0.65 agent=claude-code evidence=test_pass age=1d claims=1
# → build on it, skip re-verification
# Someone edits auth.py without re-testing
$ akf check auth.py
STALE trust=0.65 agent=claude-code evidence=test_pass age=1d claims=1 reason=modified_after_stamp
# → re-verify before trusting (exit code 1 — gate CI or hooks on it)
```
Stamps are trail markers agents leave for other agents — across sessions, across tools (Claude Code → Cursor → Copilot), across teams. Humans get the same trail: who made this file, AI or human, was it tested, can we trust it.
| What travels with the file | How |
|------|-----|
| **Trust score** | 0–1 confidence, weighted by evidence and source tier |
| **Verification evidence** | tests passed, type check clean, human reviewed — with timestamps |
| **Source provenance** | SEC filing → analyst → AI agent chain |
| **Compliance** | One command: `akf audit file --regulation eu_ai_act` |
## Don't trust the stamp — re-run it
A signature proves *who* said it; a replay proves it *could have been true*. A stamp can carry a **falsifiable probe recipe**, so the next agent re-verifies the claim instead of trusting the label:
```console
# Stamp with a recipe that can be re-run
$ akf stamp auth.py --agent claude-code --evidence "42/42 tests passed" --replay "pytest -q"
# Later — re-run the probe instead of trusting the stamp
$ akf replay auth.py --run
CONFIRMED inputs=intact
# A dependency moved since the stamp was written
$ akf replay auth.py --run
CONFIRMED_DRIFTED inputs=drifted # probe still passes, but against a changed world — re-check
```
`REFUTED` when the probe fails, `UNREPLAYABLE` when there's no recipe. This is the answer to "a trusted source can still be wrong": trust stops depending on who signed it, for any claim with a runnable check.
## Quickstart
```bash
pip install akf # Python
npm install akf-format # TypeScript / Node.js
akf doctor # Check your install — detects PATH issues and guides setup
```
> **`akf` command not found?** Run `akf doctor` to auto-detect your setup, or use `python3 -m akf` (always works).
> - Install with pipx: `pipx install akf` (recommended — auto-handles PATH)
> - **Windows:** use `python3 -m akf` or install via `pipx`
```bash
# The core loop — stamp what you verified, check before you trust
akf stamp auth.py --agent claude-code --evidence "42/42 tests passed"
akf check auth.py # OK trust=0.65 agent=claude-code evidence=test_pass age=0d
```
```python
import akf
# Same loop from Python
akf.stamp_file("auth.py", agent="claude-code", evidence=["42/42 tests passed"])
result = akf.check_file("auth.py")
print(result.summary_line()) # OK trust=0.65 agent=claude-code evidence=test_pass age=0d claims=1
# Embed into Office docs, PDFs, images — any format
akf.embed("report.docx", claims=[...], classification="confidential")
# Audit for compliance (EU AI Act, HIPAA, SOX, GDPR, NIST AI, ISO 42001)
result = akf.audit("report.akf", regulation="eu_ai_act")
print(f"Compliant: {result.compliant}")
```
**TypeScript / Node.js** (`akf-format`):
```typescript
import { create, validate, effectiveTrust, stampFile } from 'akf-format';
// Create a trust-stamped unit from any AI output
const unit = create('Revenue was $4.2B, up 12% YoY', 0.98, {
source: 'SEC 10-Q',
agent: 'claude-code',
});
// Validate against the AKF schema
const { valid } = validate(unit);
// Compute effective trust for a claim
const trust = effectiveTrust(unit.claims[0]);
console.log(`valid: ${valid}, score: ${trust.score}, decision: ${trust.decision}`);
// Stamp trust metadata directly into a file (markdown, json, code, …)
stampFile('report.md', { agent: 'claude-code', evidence: 'tests pass' });
```
> Full TypeScript API and more examples: [`typescript/README.md`](typescript/README.md).
## For AI Agents
AKF is designed **agent-first**. One-line APIs for checking, stamping, streaming, and auditing.
```python
import akf
# Check before you trust — can I build on this file without re-verifying?
result = akf.check_file("auth.py")
if result.status == "OK": # fresh stamp, verified evidence
... # skip re-verification, save the tokens
# LOW / STALE / UNSTAMPED → verify before trusting
# Stamp with evidence (auto-detected: test_pass, type_check, human_review, etc.)
akf.stamp("Fixed auth bypass", kind="code_change",
evidence=["42/42 tests passed", "mypy: 0 errors"],
agent="claude-code", model="claude-sonnet-4-20250514")
# Stream trust metadata in real-time
with akf.stream("output.md", model="gpt-4o") as s:
for chunk in llm_response:
s.write(chunk)
# Trust-annotated git commits (uses git notes)
akf.stamp_commit(content="Refactored auth module", kind="code_change",
evidence=["all tests pass"], agent="claude-code")
print(akf.trust_log(n=10)) # + ACCEPT ~ LOW - REJECT ? none
```
## Multi-Agent Teams
AKF supports multi-agent orchestration — Claude Agent Teams, Copilot Cowork, Codex multi-agent, and any A2A-compatible platform.
```python
import akf
# Agent-to-agent delegation with trust ceiling
policy = akf.DelegationPolicy(
delegator="lead-agent", delegate="research-bot",
trust_ceiling=0.7, allowed_actions=["search", "summarize"]
)
result = akf.delegate(parent_unit, policy)
# Multi-agent streaming session
with akf.TeamStream(["research", "writer", "reviewer"]) as ts:
ts.write("research", "Found 3 sources", confidence=0.8)
ts.write("writer", "Drafted summary", confidence=0.75)
ts.write("reviewer", "Approved with edits", confidence=0.9)
scores = ts.aggregate() # per-agent + team trust
# Cross-platform agent identity
card = akf.create_agent_card(name="Research Bot", platform="claude-code",
capabilities=["search", "summarize"])
akf.verify_agent_card(card) # SHA-256 hash verification
# Team certification (per-agent breakdown)
report = akf.certify_team("src/", min_trust=0.7)
# report.all_agents_certified — each agent must individually pass
```
**CLI:**
```bash
akf agent create --name "Bot" --platform claude-code --capabilities search,summarize
akf agent list
akf agent verify
akf agent export-a2a --output card.json # A2A protocol bridge
akf agent import-a2a card.json
akf certify src/ --team # Per-agent breakdown
```
## MCP Server
AKF ships an [MCP](https://modelcontextprotocol.io) server so any AI agent can create, validate, scan, and audit trust metadata.
```bash
# Install from the repo
pip install ./packages/mcp-server-akf
```
```json
{
"mcpServers": {
"akf": {
"command": "python",
"args": ["-m", "mcp_server_akf"]
}
}
}
```
**11 MCP tools:** `check_file` · `replay_file` · `create_claim` · `validate_file` · `scan_file` · `trust_score` · `stamp_file` · `audit_file` · `embed_file` · `extract_file` · `detect_threats`
## Ambient Trust
AKF works where AI agents work. Drop a config file, and every AI-generated file carries trust metadata automatically.
| Agent | How it works |
|-------|-------------|
| **Claude Code** | Plugin: `/plugin marketplace add HMAKT99/AKF` → `/plugin install akf` — auto-stamp hook + check skill. Or reads `CLAUDE.md` |
| **Cursor** | Reads `.cursorrules` — stamps AI edits before you review |
| **Windsurf** | Reads `.windsurfrules` — stamps AI edits with trust metadata |
| **GitHub Copilot** | Reads `.github/copilot-instructions.md` (native) + shell hook for CLI |
| **OpenAI Codex** | Reads `AGENTS.md` — stamps files in cloud sandbox and local |
| **OpenClaw** | Skill on ClawHub: `clawhub install akf` — check/stamp protocol + memory trust |
| **Hermes Agent** | agentskills.io skill: `hermes skills tap add HMAKT99/AKF` — files, memories, and skill supply-chain |
| **Manus / Other Agents** | MCP server + shell hook — works with any agent that supports MCP or CLI |
| **Any MCP agent** | 11 MCP tools — check, replay, stamp, audit, embed, extract, detect, validate, scan, trust, create |
| **Any CLI tool** | `eval "$(akf shell-hook)"` — intercepts `claude`, `chatgpt`, `aider`, `openclaw`, `ollama`, `manus` |
**The trust pipeline:**
```
Agent writes code → Git commit stamped → CI runs akf certify → Team reviews with context
```
Set up in 60 seconds:
```bash
# 1. Agent stamps its own work (already in this repo)
cat CLAUDE.md # or .cursorrules / .windsurfrules / AGENTS.md / .github/copilot-instructions.md
# 2. Git hooks stamp every commit
akf init --git-hooks
# 3. CI certifies trust on every PR
# uses: HMAKT99/AKF/extensions/github-action@main
# 4. Shell hook intercepts AI CLI tools
eval "$(akf shell-hook)"
```
## Skills
AKF provides [agent skill files](skills/) that AI agents can discover and use. Drop these into your agent's context:
| Skill | What it does |
|-------|-------------|
| [`check.md`](skills/check.md) | Check a file's trust before building on it |
| [`stamp.md`](skills/stamp.md) | Stamp trust metadata onto AI outputs |
| [`audit.md`](skills/audit.md) | Audit files for regulatory compliance |
| [`scan.md`](skills/scan.md) | Security scan files and directories |
| [`embed.md`](skills/embed.md) | Embed trust metadata into Office/PDF/images |
| [`detect.md`](skills/detect.md) | Run 10 security detection classes |
| [`stream.md`](skills/stream.md) | Stream trust metadata in real-time |
| [`git.md`](skills/git.md) | Trust-annotated git workflows |
| [`convert.md`](skills/convert.md) | Convert between formats |
| `delegate` | Agent-to-agent trust delegation |
| `team` | Multi-agent streaming sessions |
## Format at a Glance
**Compact** (~15 tokens — optimized for AI):
```json
{"v":"1.0","claims":[{"c":"Revenue was $4.2B","t":0.98,"src":"SEC 10-Q"}]}
```
**Descriptive** (human-readable — same data):
```json
{"version":"1.0","claims":[{"content":"Revenue was $4.2B","confidence":0.98,"source":"SEC 10-Q"}]}
```
**Full** (with provenance, decay, AI flags, security):
```json
{"v":"1.0","by":"sarah@acme.com","label":"confidential","inherit":true,
"claims":[
{"c":"Revenue $4.2B","t":0.98,"src":"SEC 10-Q","tier":1,"ver":true,"decay":90},
{"c":"H2 will accelerate","t":0.63,"tier":5,"ai":true,"risk":"AI inference"}
],
"prov":[
{"hop":0,"by":"sarah@acme.com","do":"created","at":"2025-07-15T09:30:00Z"},
{"hop":1,"by":"copilot-agent","do":"enriched","at":"2025-07-15T10:15:00Z"}
]}
```
## Works With Every Format
AKF embeds natively — no sidecars needed for most formats:
| Format | How It Works |
|--------|-------------|
| `.akf` | Native standalone knowledge file |
| `.docx` `.xlsx` `.pptx` | OOXML custom XML part |
| `.pdf` | PDF metadata stream |
| `.html` | JSON-LD `