First project

This guide takes you through the full plan-to-ship loop in one sitting. By the end you’ll have a project tracking a real issue, a repository with code in it, an agent that opened a PR against that issue, and a CI pipeline that ran on it. Everything stays inside the one ProxifAI deployment from the Quickstart.

1. Create a project

Plan → New project

Fill in:

Field	Notes
Name	What you’re shipping (“Auth Refresh”, “Q2 Onboarding redesign”)
Team	Use the team you set up in Create your workspace
Status	backlog if not started; planned once scoped; in_progress once you flip the switch
Health	Independent dimension — on_track is the right default; flip to at_risk / off_track later
Lead, target date, priority	Optional — set them or skip

pfai project create "Auth Refresh" \
  --team backend --lead alice \
  --target-date 2026-06-30 --priority high

The project shows up in your team’s sidebar and the project list. Its dashboard is empty — issues populate it as you create them.

2. Push a repo

Code → New repository

Choose visibility, optional README, and the default branch (main).

Once it exists, clone over HTTPS:

git clone http://localhost:3000/git/<your-org>/<repo>.git
cd <repo>
echo "# Auth refresh" > README.md
git add README.md
git commit -m "initial commit"
git push origin main

Use a PAT as the password if you’re prompted. The forge accepts pfai_* tokens directly with git config credential.helper.

Link the repo to the project from Project → Settings → Repositories (or pfai project repos add <project-id> <owner>/<repo>). Linking surfaces the repo’s commits, PRs, and releases on the project dashboard.

3. Open an issue

Plan → Issues → New

The minimum required field is the title; everything else has team defaults. Status starts at backlog — flip to todo when you’re ready to pick it up.

pfai task create \
  --title "Migrate to OIDC for the admin login" \
  --type bug --priority high \
  --team backend --project <project-id> \
  --label auth,production

Issues are numbered per team (BACK-42). You can Closes #BACK-42 from a PR description and the merge transitions the issue to done automatically.

4. Dispatch an agent

This is the part that makes ProxifAI’s AI useful — issues can be assigned to AI agents the same way they’re assigned to people.

pfai task dispatch BACK-42 --agent claude-code --branch main

What happens under the hood (architecture):

1. The dispatcher creates an AgentExecution row scoped to the issue
2. The instances subsystem provisions a per_execution container from the claude-code image
3. The agent boots inside the container with PFAI_TOKEN / PFAI_SERVER / PFAI_EXECUTION_ID env vars
4. The container clones the repo, the agent reads the issue, makes changes, runs tests, opens a PR via pfai pr create
5. Streaming output reaches you through the agent’s terminal in the web UI

Watch progress at Plan → BACK-42 → Activity or stream from the CLI:

pfai logs agent-execution/<execution-id>
pfai wait agent-execution/<execution-id>   # blocks until terminal state

If you don’t have an LLM provider configured yet, the agent will surface “no LLM provider configured” — set one up under Settings → Model Providers first. See AI Gateway for the catalog.

5. Review the PR

When the agent finishes, a PR appears under the repo with the agent’s commit. Review it like any other:

• The diff tab shows changes side-by-side or unified
• Reviews carry verdicts (APPROVED / CHANGES_REQUESTED / COMMENTED / PENDING)
• Required CI checks gate the merge button
• The PR’s Closes #BACK-42 (or similar) auto-closes the issue on merge

pfai pr view <number>
pfai pr review <number> --verdict APPROVED --body "Looks good"
pfai pr merge <number> --method squash

6. Try AI chat

Open the AI tab and start a conversation. Four modes are available — see Chat Modes for the full breakdown:

Mode	Use it for
ask	Questions about the codebase, issues, or docs — read-only
plan	Read-only analysis with full forge access (great for code review)
code	Live development inside a container with shell, file, git, browser tools
build	Same tools as code, framed as a feature-shipping session

Reference any entity with @-mentions: @<repo>, @<file-path>, @<issue-id>, @<pr-number>, @<doc-title>. Mentions pull the full payload into context (not just chunks).

What you’ve now seen

In about thirty minutes you’ve touched most of the platform: a project, a repo, an issue with full traceability, an agent dispatched in an isolated container, a PR review flow, and the AI chat. From here, every other section of the docs builds on these primitives — workflows automate sequences of these actions, triggers fire them on platform events, and integrations push them out to external systems.