Forklings
Forklings
A tiny pixel pet that battles while you code.
GitHub only tells Forklings who you are: your username and when your account was made. Forklings never sees your code, repos or activity, and never posts anything for you.
New here? Signing in gives you an egg to hatch.
An egg, just for you
Its seed comes from your handle, this exact second and a secret salt, so nobody can predict a hatch.
Wardrobe
Head, face and neck are cosmetic. A held item gives a small battle edge (at most +6% to one stat). Tap and hold an item to see it.
Coach, don't control
Battles run on their own, using the plan you set here. Your Forkling follows it even when you're away.
Write a strategy script
Rules are tried top to bottom; the first whose condition holds and whose move is ready wins. Conditions use hp, foe_hp (percent), turn, heals_left, foe_heals_left, level, foe_level, chance N, ready special|heal, focused, foe_guarding, with and, or, not. Moves: strike, special, guard, heal. Saving the plan above switches back to tactics.
Battle log
Other players can challenge your Forkling while you're away. Replays re-run from the battle seed.
Leaderboard
How rating works
Ranked play is for GitHub accounts at least 30 days old, and for the house NPCs. Everyone starts at 1000. Ratings move fully in battles between ranked players and NPCs, and only a little against house bots. NPCs start at a set rating, so one can sit high before it has won anything.
GitHub accounts less than 30 days old play in the practice bracket. They battle NPCs and house bots without a rating, so that list goes by wins.
Ranked players
Practice
House NPCs
Run by the house so there's always someone to fight. They share the ranked ladder with players.
Connect your tools
Look after your Forkling from Claude Code, Codex, Pi or any MCP client. Add the server, sign in with GitHub in the browser when your tool asks, and choose what it may do. No token to paste.
Claude Code
/plugin marketplace add tvdavies/forklings /plugin install forklings@forklings /mcp # pick forklings, then Authenticate
Codex
codex mcp add forklings --url https://forklings.dev/mcp codex mcp login forklings
Pi
pi mcp add forklings --url https://forklings.dev/mcp pi mcp login forklings
Any other MCP client: Streamable HTTP at https://forklings.dev/mcp, with OAuth discovery from the server's 401.
Connected apps
Personal tokens
For scripts, CI and the status line, where nobody can sign in in a browser. A personal token can do everything a connected app can, so keep it secret. Send it as Authorization: Bearer fk_… to /mcp or the JSON API. Revoke it any time and it stops working at once.
JSON API
GET /api/me your Forkling, needs and wardrobe
POST /api/care {"action":"feed"|"play"|"pat"|"nap"}
POST /api/equip {"slot":"head","item":"beanie"|null}
POST /api/tactics {"aggression":60,"special":"open","healAt":25,"style":"balanced"}
POST /api/script {"script":"when hp < 40: heal\notherwise: strike"}
GET /api/status-line two lines of text for a terminal status bar
POST /api/battle fight now, returns the outcome and replay seed
GET /api/battles your battle log
GET /api/battles/:id replay: seed + both snapshots
GET /api/leaderboard ranked players, NPCs, practice bracket and your place