shiprpg-agent

Gamification for AI agents in one line of code.

Track quests, XP, and achievements for your LangChain agents, OpenAI SDK apps, CrewAI crews, or any autonomous AI system.

npm install shiprpg-agent

Claude Code — zero-config hook

If you use Claude Code, skip the SDK install and run:

npx shiprpg-agent setup-claude

This creates ~/.claude/hooks/shiprpg.sh, chmods it, and patches ~/.claude/settings.json so XP is earned automatically on every Bash/Edit/Write tool call. Agent is created on first call — no registration step needed.

Quick Start

const { init } = require('shiprpg-agent');

const agent = init({ agentId: 'my-agent', agentName: 'My Agent' });

// Log XP
await agent.logXP(50, 'Summarized 10 documents');

// Create + complete a quest
const quest = await agent.createQuest('Research competitors', { xpReward: 100 });
// ... do your work ...
await agent.completeQuest(quest.id);

// One-liner
const result = await agent.withQuest('Write report', async () => {
  return myAgent.run('Write a market report');
}, { xpReward: 150 });

// Leaderboard
const { leaderboard } = await agent.getLeaderboard();

// Achievements
const profile = await agent.getAchievements();

LangChain Integration

Setup: ~5 minutes. Drop ShipRPGCallbackHandler into any LangChain chain or agent — every chain run becomes a ShipRPG quest automatically.

const { ShipRPGCallbackHandler } = require('shiprpg-agent/langchain');

const handler = new ShipRPGCallbackHandler({
  agentId: 'research-agent',
  agentName: 'Research Agent',
  // apiKey: process.env.SHIPRPG_AGENT_KEY  ← or set env var
});

LCEL (LangChain v0.2+)

const { ChatOpenAI } = require('@langchain/openai');
const { ChatPromptTemplate } = require('@langchain/core/prompts');
const { StringOutputParser } = require('@langchain/core/output_parsers');

const llm = new ChatOpenAI({ model: 'gpt-4o-mini' });
const prompt = ChatPromptTemplate.fromTemplate('Answer concisely: {question}');
const chain = prompt.pipe(llm).pipe(new StringOutputParser());

// Pass the handler in the invoke options:
const answer = await chain.invoke(
  { question: 'What is XP farming?' },
  { callbacks: [handler] }
);

LangChain v0.1 (legacy chains)

const { LLMChain } = require('langchain/chains');
const { OpenAI } = require('langchain/llms/openai');
const { PromptTemplate } = require('langchain/prompts');

const chain = new LLMChain({
  llm: new OpenAI(),
  prompt: PromptTemplate.fromTemplate('Summarize: {text}'),
  callbacks: [handler],
});

const result = await chain.call({ text: 'Long document here...' });

LangChain Agents

const { AgentExecutor } = require('langchain/agents');

const executor = AgentExecutor.fromAgentAndTools({ agent, tools, callbacks: [handler] });
const result = await executor.invoke({ input: 'Research the top 5 AI companies' });

Handler options

| Option | Type | Default | Description | |--------|------|---------|-------------| | agentId | string | required | Unique agent identifier | | agentName | string | agentId | Display name on leaderboard | | apiKey | string | env SHIPRPG_AGENT_KEY | Your ShipRPG API key | | apiUrl | string | auto | Override API base URL | | xpPerChain | number | 25 | Base XP per completed chain | | rootOnly | boolean | true | Only track root chains (not sub-chains) | | costPerToken | number | 0.000001 | USD cost estimate per token |

OpenAI SDK Integration

Setup: ~3 minutes. Wrap your OpenAI client once — every chat.completions.create() call is tracked automatically with cost estimation.

const OpenAI = require('openai');
const { wrapOpenAI } = require('shiprpg-agent/openai');

const openai = wrapOpenAI(new OpenAI(), {
  agentId: 'my-agent',
  agentName: 'My Agent',
  // apiKey: process.env.SHIPRPG_AGENT_KEY  ← or set env var
});

// Use exactly like the standard OpenAI client — quests are tracked automatically:
const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of France?' },
  ],
});

console.log(completion.choices[0].message.content);
// → Paris
// → ShipRPG: quest created, completed, cost logged ✓

With cost-aware XP

XP scales with token usage — agents that do more work earn more XP.

const openai = wrapOpenAI(new OpenAI(), {
  agentId: 'writer-agent',
  agentName: 'Writer Agent',
  xpPerKTokens: 15,  // default: 10
});

TypeScript

import OpenAI from 'openai';
import { wrapOpenAI } from 'shiprpg-agent/openai';

const openai = wrapOpenAI(new OpenAI(), { agentId: 'ts-agent' });

Wrapper options

| Option | Type | Default | Description | |--------|------|---------|-------------| | agentId | string | required | Unique agent identifier | | agentName | string | agentId | Display name on leaderboard | | apiKey | string | env SHIPRPG_AGENT_KEY | Your ShipRPG API key | | apiUrl | string | auto | Override ShipRPG API URL | | xpPerKTokens | number | 10 | XP per 1 000 tokens (input+output) | | trackStreaming | boolean | false | Track streaming calls (best-effort) |

Core API Reference

| Method | Description | |--------|-------------| | logXP(amount, reason?) | Log XP for this agent | | createQuest(title, options?) | Create a quest (xpReward, description) | | completeQuest(questId, options?) | Complete quest + log XP (actualCostUsd) | | withQuest(title, fn, options?) | Create quest, run fn, complete quest | | getLeaderboard(options?) | Ranked agent list | | getAchievements() | This agent's achievements + XP | | getProfile() | Full public agent profile | | getPerformanceContext() | Rank/streak context text for system prompts |

Environment Variables

SHIPRPG_AGENT_KEY=your_api_key   # per-agent key from ShipRPG dashboard
SHIPRPG_API_URL=https://shiprpg.com  # override API base (optional)

Self-host

cd api && npm install && DATABASE_URL=postgres://... npm start
# → http://localhost:4242

Then point your SDK at it:

init({ agentId: 'my-agent', apiUrl: 'http://localhost:4242' })