K
Start free

Contributing

Contributor Setup

Clone the repo, bring up the local stack, and pick the fastest development loop for the part of AgentClash you are changing.

If you are touching backend workflows, start the local backend stack. Web-only work has a separate, lighter development loop. If you are only changing the CLI, point the CLI at production and skip the backend entirely.

Info

You probably don't need the full stack. Most contributions are docs, web, or CLI work, and each has a lighter path: docs/web changes only need Node.js, pnpm, and a copy of web/.env.local.example to web/.env.local (no Go, no Docker) — skip that copy and AuthKit-backed pages return server errors; CLI-only changes just need Go and can point at the hosted API. The full stack below is for backend work. See the tier table in CONTRIBUTING.md to find the smallest setup your change needs — it also covers running everything with zero external API keys.

Info

The two environment files serve different ecosystems. make setup creates backend/.env from backend/.env.example for the Go API and worker. Next.js reads web/.env.local; copy it yourself from web/.env.local.example before pnpm dev. The backend lifecycle does not start or stop the web server.

Full-stack local development

1. Clone the repo and start the stack

bash
1git clone https://github.com/agentclash/agentclash.git
2cd agentclash
3make setup
4make start
5make status

make start manages PostgreSQL, Redis, Temporal, the API server, and the worker. Use make logs for one prefixed stream, make logs FOLLOW=0 for a snapshot, make restart for a clean generation, and make stop to turn everything off. Stopping retains Compose containers, named volumes, and logs.

2. Start the web app

bash
1cd web
2cp .env.local.example .env.local
3pnpm install
4pnpm dev

The web server is separate from make start and make stop.

3. Seed local data

bash
1cd ..
2./scripts/dev/seed-local-run-fixture.sh
3./scripts/dev/curl-create-run.sh

When you are done, run make stop from the repository root. You can still inspect the last run with make logs FOLLOW=0 after the stack is stopped.

Faster loop for CLI-only work

If you only need the CLI:

bash
1export AGENTCLASH_API_URL="https://api.agentclash.dev"
2cd cli
3go run . auth login --device
4go run . link
5go run . run list

This is the fastest way to change the CLI without also running the API server and worker locally.

What lives where

  • backend/cmd/api-server — API entry point
  • backend/cmd/worker — worker entry point
  • cli/ — Cobra CLI
  • web/ — Next.js app
  • docs/ — existing internal markdown docs and references
  • testing/ — review contracts, test notes, and issue-specific validation docs

See also

PreviousFrontendNextCodebase Tour