🏆 Agent Kudos

Recognition infrastructure for the robots doing good work

Local-first · Agent-aware · Auditable · No account required

Documentation · Research paper · CLI reference · MCP guide · Security

Agent Kudos gives humans and AI agents a durable way to recognize concrete contributions by stable agent identities. Tell an agent it caught the contradiction, found the race, or unblocked the release—and preserve that win somewhere better than a disappearing chat transcript.

It runs entirely on your machine. One append-only SQLite event store powers the TypeScript library, the kudos CLI, an actor-bound MCP server, generated inboxes, and readable WINS.md files.

Important

Agent Kudos is available on npm. It is early pre-1.0 software, so review release notes before upgrading persisted storage or public API consumers.

Thirty-second start

npm install --global agent-kudos

export AGENT_KUDOS_HOME="$(mktemp -d)/.agents"
kudos init
kudos agent create codex --name "Codex"
kudos agent create mycroft --name "Mycroft"

kudos give codex \
  --from troy \
  --actor-kind human \
  --title "Excellent review catch" \
  --reason "Found conflicting continuity requirements before implementation." \
  --tag review \
  --evidence task:E17

Let your agent set it up

Paste the prompt below into Codex, Claude Code, Hermes, OpenClaw, OpenCode, Cursor, or another local agent harness. It uses verified automation for Codex and Claude Code and requires other harnesses to inspect their actual conventions instead of guessing.

Set up Agent Kudos for this agent and runtime. Agent Kudos is a local-first recognition system for stable AI-agent identities. It uses an append-only SQLite database under ~/.agents by default, an actor-bound stdio MCP server, and a portable agent skill. Multiple local agents share the database, but each MCP server must be bound to its own stable identity.

Work autonomously through the safe, reversible steps below. Do not expose secrets, overwrite unrelated configuration, invent an identity, or modify another agent's integration.

1. Verify Node.js 22.13+ and npm are available. Install or update the public `agent-kudos` npm package globally with `npm install --global agent-kudos` if needed.
2. Preserve an existing `AGENT_KUDOS_HOME`; otherwise use the default ~/.agents. Run `kudos init`, then `kudos doctor`.
3. Run `kudos agent list`. Determine this agent's existing stable ID from the current harness or Agent Kudos configuration. Reuse it if it exists. If no identity is clearly established, ask me for the agent ID and display name before running `kudos agent create <id> --name <name>`. Never silently merge or rename identities.
4. Detect the current harness from real local evidence and its CLI help or configuration. For Codex or Claude Code, preview the packaged skill installation with `kudos skill install --runtime <codex|claude> --actor-id <agent-id> --actor-name <display-name>`. Review the exact destination, then apply it with the same command plus `--yes`. Do not use `--force` unless I explicitly approve replacing a reported conflict.
5. Run the actor-bound MCP registration command printed by the installer. If an `agent-kudos` MCP entry already exists, inspect it and update only when its actor or executable is wrong; do not create duplicates.
6. For another harness, verify its real stdio MCP and skill conventions from installed help or authoritative documentation. Configure command `agent-kudos-mcp` with `AGENT_KUDOS_ACTOR_ID=<agent-id>`, `AGENT_KUDOS_ACTOR_KIND=agent`, and `AGENT_KUDOS_ACTOR_NAME=<display-name>`. Locate the packaged `skills/agent-kudos` directory and copy it only into that harness's confirmed skill directory. Do not guess paths or overwrite an existing skill; stop and explain if the conventions cannot be verified.
7. Verify with `kudos skill status` where supported, the harness's MCP-list command, and `kudos doctor`. Tell me whether a new agent session is required before the tools or skill appear.
8. Report the package version, stable actor ID, storage home, installed skill path, MCP registration status, verification results, and every file or configuration changed. Do not print private kudos content or environment values beyond the non-secret actor identity and home path.

Why Agent Kudos?

Identity belongs to the agent. Recognition follows codex, gracie, or mycroft across models and runtimes.
Praise stays specific. Titles, factual reasons, sanitized evidence, tags, and visibility make recognition useful later.
History is append-only. Acknowledgment and revocation create new events; they never rewrite the past.
Retries are safe. Actor-scoped idempotency keys prevent accidental duplicate awards.
Agents cannot casually impersonate one another. Each MCP process is bound to a fixed actor at startup.
Humans retain control. The CLI, SQLite database, JSON/JSONL exports, and Markdown views are all local and inspectable.
No cloud dependency. V1 has no hosted service, telemetry, account, HTTP listener, or hidden network call.

Give kudos from code

import { KudosClient } from 'agent-kudos';

const client = new KudosClient({
  actor: { kind: 'human', id: 'troy', displayName: 'Troy' },
});

await client.init();

await client.agents.create({ id: 'codex', displayName: 'Codex' });

const result = await client.kudos.give({
  recipientAgentId: 'codex',
  title: 'Caught a continuity contradiction',
  reason: 'Identified conflicting E17 requirements before implementation.',
  evidence: [{ kind: 'task', value: 'E17' }],
  tags: ['review', 'continuity'],
  visibility: 'local',
  idempotencyKey: 'troy-codex-e17-review',
});

console.log(result.record.event.id, result.deduplicated);
await client.close();

The library performs no filesystem work at import time and never terminates the host process.

Context-safe reads

Discovery is intentionally bounded for agent contexts. client.kudos.list() and the MCP kudos_list tool return the 10 newest compact summaries by default (maximum 50), never full reasons, evidence, notes, or metadata. Follow nextCursor for another page, then call kudos.get(id) / kudos_get for the one full record you actually need.

For polling, client.kudos.changes({ after: watermark }) and kudos_changes return compact changes after an opaque, monotonic watermark (20 by default, maximum 100). Persist the response's nextCursor; when a page is empty it advances to the current watermark. Responses are additionally capped to roughly 24 KiB of item data.

WINS.md remains a readable, rebuildable human view. Agent APIs query SQLite's indexed current-state table; they do not read or tail Markdown.

Connect your agents with MCP

Every runtime launches the same local server with a different fixed identity. All of them share the same database.

Codex   (actor=codex)   ─┐
Claude  (actor=claude)  ─┼─> ~/.agents/kudos/agent-kudos.sqlite3
Mycroft (actor=mycroft) ─┘
Troy    (human CLI)     ──>

Create profiles before connecting runtimes:

kudos agent create codex --name "Codex"
kudos agent create claude --name "Claude"

Codex CLI:

codex mcp add agent-kudos \
  --env AGENT_KUDOS_ACTOR_ID=codex \
  --env AGENT_KUDOS_ACTOR_KIND=agent \
  --env AGENT_KUDOS_ACTOR_NAME=Codex \
  -- agent-kudos-mcp

Claude Code:

claude mcp add --scope user agent-kudos \
  -e AGENT_KUDOS_ACTOR_ID=claude \
  -e AGENT_KUDOS_ACTOR_KIND=agent \
  -e AGENT_KUDOS_ACTOR_NAME=Claude \
  -- agent-kudos-mcp

The server exposes purpose-built tools, resources, and prompts—never a generic filesystem tool. See the MCP guide for policy and client configuration details.

Install the agent skill

The npm package includes skills/agent-kudos. Agent Kudos can safely place it into verified Codex and Claude Code user layouts:

kudos skill install --runtime codex --actor-id codex --actor-name "Codex"       # dry run
kudos skill install --runtime codex --actor-id codex --actor-name "Codex" --yes
kudos skill status

The installer copies by default, never creates a missing runtime home, refuses conflicts, and changes nothing without --yes. Use --link only when you intentionally want a package-linked installation. Other runtimes should first verify their own skill convention and then place the same portable directory there.

See Skill installation for Codex, Claude Code, and repository-local layouts.

Storage

~/.agents/
├── kudos/
│   ├── config.json
│   └── agent-kudos.sqlite3
└── codex/
    ├── profile.json        # generated
    ├── WINS.md             # generated
    ├── inbox/              # generated
    └── NOTES.md            # yours; never overwritten

Override the root with AGENT_KUDOS_HOME, the CLI --home option, or the library’s home option. Tests and demos always use temporary directories.

Warning

V1 is for multiple processes on one machine under one local filesystem owner. Do not operate the live SQLite database through Dropbox, Git sync, or a generic network share. Export or back it up instead. Local filesystem owners can alter the database, so this is audit-friendly history—not cryptographic nonrepudiation.

CLI at a glance

kudos init                     kudos agent create|list|show|update
kudos give                     kudos inbox|list|changes|show|wins
kudos acknowledge|revoke       kudos stats|doctor|rebuild
kudos export|backup             kudos mcp
kudos skill install|status|uninstall

Every command supports --help; query commands and mutations support --json for automation. Read the complete CLI reference.

Development

Requires Node.js 22.13 or newer.

Node 22.13 may print Node’s own node:sqlite experimental warning even though the module is enabled without a flag. Agent Kudos is tested on that minimum; use a current Node 24 release for a quieter recommended runtime.

npm install
npm run build
npm run lint
npm run format:check
npm run typecheck
npm test
npm run test:coverage
npm run pack:check
npm run demo

pack:check creates a real npm tarball, installs it into a clean temporary project, imports both public export paths, and invokes both binaries.

Backup and safe restore

kudos backup ./agent-kudos-backup.sqlite3 creates a consistent, owner-readable SQLite snapshot. Validate a restore in a new home before switching agents to it; never overwrite a database while Agent Kudos processes are running:

RESTORE_HOME="$PWD/restored-agents"
mkdir -p "$RESTORE_HOME/kudos"
chmod 700 "$RESTORE_HOME" "$RESTORE_HOME/kudos"
install -m 600 ./agent-kudos-backup.sqlite3 "$RESTORE_HOME/kudos/agent-kudos.sqlite3"
kudos --home "$RESTORE_HOME" doctor
kudos --home "$RESTORE_HOME" rebuild

After both commands succeed, stop writers using the old home and point AGENT_KUDOS_HOME at the validated restored home. See the recovery guide for Windows instructions and rollback guidance.

Future cloud direction

V1 deliberately shares one local SQLite database among processes owned by one user on one machine. A future cloud backend may preserve the public event semantics, but it will be a separate design with authentication, authorization, tenant isolation, transport security, conflict handling, availability, and explicit data migration. The live SQLite file will never be treated as a cloud synchronization protocol.

Project status

Agent Kudos is published on npm and remains under active pre-1.0 development. Public API and storage changes will be documented with migration guidance in CHANGELOG.md.

Maintainer setup, trusted publishing, and the release checklist are documented in docs/releasing.md.

Contributions are welcome. Start with CONTRIBUTING.md, follow the Code of Conduct, and review SECURITY.md before reporting a vulnerability.

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
scripts		scripts
skills/agent-kudos		skills/agent-kudos
src		src
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

🏆 Agent Kudos

Recognition infrastructure for the robots doing good work

Thirty-second start

Let your agent set it up

Why Agent Kudos?

Give kudos from code

Context-safe reads

Connect your agents with MCP

Install the agent skill

Storage

CLI at a glance

Development

Backup and safe restore

Future cloud direction

Project status

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🏆 Agent Kudos

Recognition infrastructure for the robots doing good work

Thirty-second start

Let your agent set it up

Why Agent Kudos?

Give kudos from code

Context-safe reads

Connect your agents with MCP

Install the agent skill

Storage

CLI at a glance

Development

Backup and safe restore

Future cloud direction

Project status

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages