loopshouse

The Loops House CLI — authenticate, ideate with AI, query knowledge graphs, and submit projects from your terminal or an AI agent. Built with incur, so the same definitions power a CLI, an MCP server, and an agent skill.

Install

One command sets up an event — it installs the CLI globally, writes the event's agent skill into your coding agents (Claude Code + the .agents standard), and signs you in:

npx loopshouse add <event-slug>

Re-run it any time to refresh the skill with the event's latest sponsors and deadlines. Or install manually:

npm i -g loopshouse
# or run from this repo:
bun run bin/loops.ts --help

Quick start

loops events                            # don't know the slug yet? list active/upcoming events (no auth needed)
loops auth login --provider github     # or --provider google, or --email [email protected]
loops ideate -e <event> -m "give me a project idea"
loops ideate -e <event> -m "go deeper on idea 2"        # session continues automatically
loops ideate -e <event> -m "how do I approach it?" --problems <problem>   # compete: focus on a problem
loops knowledge query -e <event> -s <sponsor> -q "how do I use the sponsor's SDK?"
loops knowledge query -e <event> -p <problem> -q "what does the problem require?"   # compete events
loops project create -e <event> --name "My Project" --repoUrl https://github.com/me/proj
loops project get -e <event>
loops project fields -e <event>                          # everything the event asks for (built-in + extra) and what's missing
loops project update -e <event> --answer <id>=<value>    # answer an extra field — the name works as the key too
loops credits -e <event>

Every event-scoped command takes --event (-e). Knowledge and evaluator commands take exactly one of --sponsor (-s, sponsor-keyed events) or --problem (-p, problem-keyed compete events). The CLI works on one event at a time (no cross-event listings); ideator conversations persist per event in ~/.loops/sessions/.

Tip: every event's playground has a "Use the skill" tab with the exact npx loopshouse add command. Append a sponsor slug (npx loopshouse add <slug> <sponsor>) to install a skill focused on that sponsor's bounties, docs, and judging criteria instead.

Commands

| Group | Commands | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | root | events [--event <slug>] (no auth needed — list active/upcoming events, or look up one by slug + its eventType; a concluded event still resolves with ended/winnersUrl, not a 404) | | root | add <event> [sponsor] (interactive setup: CLI install/update, skill into agents, auth) | | auth | login, verify, status, logout, link (attach a GitHub/Google identity when sign-in hits "multiple accounts") | | root | ideate (1 credit/turn; stateful session, --sponsors/--problems focus, --withProject, --new), session (show/--clear) | | project | get (your one project for an event), create, update (PATCH — only passed fields change; no project id, yours is resolved) | | knowledge | query (1 credit/query — graph-RAG evidence; exactly one of --sponsor/--problem) | | artifact | list, save, update, remove (ideation scratchpad) | | root | credits (agent credits), evaluate (evaluator prompt; exactly one of --sponsor/--problem; project auto-included) |

Compatibility

The 0.2.x flag spellings — --hackathonSlug, --sponsorSlug, --problemSlug, --eventSlug, and their kebab forms — still parse: a shim in bin/loops.ts maps each legacy token to its canonical flag before parsing. Skills and scripts written against 0.2.x keep working unchanged; help text shows only the canonical flags.

Authentication

Auth uses Supabase Auth against the Loops platform. Three flows:

| Flow | Command | | ------------ | --------------------------------------------------------------------------------------------- | | GitHub OAuth | loops auth login --provider github | | Google OAuth | loops auth login --provider google | | Email OTP | loops auth login --email [email protected] then loops auth verify --email [email protected] --code 123456 |

OAuth runs a localhost callback server (default port 54321, --port to change), opens your browser, and exchanges the PKCE code for a session. Tokens are stored at ~/.loops/credentials.json (mode 0600) and refreshed automatically on each command.

Agent surfaces

loops --mcp          # start as an MCP stdio server
loops mcp add        # register the MCP server with your agent
loops skills add     # generate + install skill files
loops --llms         # print the machine-readable command manifest

Configuration

| Env var | Default | Purpose | | ------------------------- | ------------------------- | -------------------- | | LOOPS_PLATFORM_URL | https://www.loops.house | Platform API origin | | LOOPS_SUPABASE_URL | (baked) | Supabase project URL | | LOOPS_SUPABASE_ANON_KEY | (baked) | Supabase anon key |

Point these at http://localhost:3000 + your local Supabase to develop against a local stack.

Develop

bun install
bun run bin/loops.ts <args>   # run from source
bun run build                 # bundle to dist/loops.js
bun run typecheck             # tsc --noEmit