# Contributor Setup

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

Source: https://www.agentclash.dev/docs/contributing/setup
Markdown export: https://www.agentclash.dev/md/docs/contributing/setup

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](https://github.com/agentclash/agentclash/blob/main/CONTRIBUTING.md#run-agentclash-locally)
> 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
git clone https://github.com/agentclash/agentclash.git
cd agentclash
make setup
make start
make 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
cd web
cp .env.local.example .env.local
pnpm install
pnpm dev
```

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

### 3. Seed local data

```bash
cd ..
./scripts/dev/seed-local-run-fixture.sh
./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
export AGENTCLASH_API_URL="https://api.agentclash.dev"
cd cli
go run . auth login --device
go run . link
go 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

- [Self-Host Starter](https://www.agentclash.dev/md/docs/getting-started/self-host)
- [Architecture Overview](https://www.agentclash.dev/md/docs/architecture/overview)
- [Datasets overview](https://www.agentclash.dev/md/docs/guides/datasets-overview)