Skip to main content

Projects overview

A project is where a team's work lives: a codebase (or set of repositories), the tasks against it, and the members who can access it. Projects give the agent scope — which repos it may read, which models apply, and how usage is attributed — and give your team a shared place to track progress.

What a project contains

Every project is a workspace with a consistent set of building blocks:

AreaWhat it holdsWho manages it
TasksUnits of work with status, assignees, and optional agent linksProject members; leads and project admins triage
ViewsSaved filters, grouping, and layouts over those tasksAnyone in the project; shared views are team defaults
MembersPeople who can see and work in the projectOrg admins and project admins
RepositoriesLinked GitHub repos, branch policy, and sync stateProject admins with repo capability
AgentsProject-scoped agent runs, model policy, and tool accessMembers run agents; admins set policy
UsageSpend and run attribution for the projectVisible to admins; rolls up to org Usage
Tasks & views

Create work items, move them through statuses, and save the views your team returns to.

Members & roles

Add people, set a project lead, and understand project vs org permissions.

Project lifecycle

Projects move through a simple lifecycle so admins can distinguish active work from archived history:

StatusMeaning
PlannedScoped but not yet started — members may be assigned, tasks may be in backlog
ActiveDefault for ongoing work — agents, tasks, and repos are in daily use
PausedTemporarily on hold — access remains, but the project is deprioritized
CompletedDelivered — read-heavy; good for reference and audit
ArchivedHidden from default directories — retained for compliance and history

Health indicators (on track, at risk, off track, no update) surface on the project overview so leads and org admins can spot stalled work without opening every task.

Creating a project

  1. New project

    From the Projects app, choose New project. Give it a name, a short key (used in task IDs like ATL-42), and optionally link one or more repositories. If your org requires project assignment before agent use, make sure the right people are added in the same session.

  2. Add members

    Open the project's Members panel and add people from your organization. Assign project admin to whoever should manage repos, policy, and membership; everyone else can be a member. Designate a project lead — the person accountable for delivery.

  3. Configure scope

    Confirm linked repositories, default branch, and any project-level model or budget overrides set by your org admin. Project policy resolves after organization policy, so inherited defaults apply unless narrowed here.

  4. Start working

    Create tasks (or import from GitHub/Linear if integrated), save a default view for the team, and open the agent scoped to this project to begin making changes.

Working with the agent in a project

When you start an agent run from a project, 4RGE resolves effective policy for that scope:

organization policy → team policy (if any) → project policy → member overrides

That means the same member may use different models or repo access in two projects. Runs started from the desktop, CLI, or cloud agents all respect this chain and attribute usage to the project.

Example: kick off a focused fix from the CLI inside a linked repo:

cd ~/work/my-service
4rged agent run \
  --project atl-platform \
  --prompt "Fix flaky integration tests in pkg/auth" \
  --output json

The run ID in the JSON output links back to the project's activity feed and org usage rollups.

Production app URLs

In production, project work lives at https://4rged.ai/projects and cloud agent runs start from https://4rged.ai/agents. Both apps share the same Supabase-backed org boundary and resolve effective policy from api.4rged.ai (/api/desktop/effective-policy) on session start. Local development serves the Projects app on port 3009 and the Agents workspace on port 3004 — see Troubleshooting if API calls fail during setup.

Who sees what

ActorProject visibility
Org memberOnly projects they are added to
Org admin / super adminAll projects in the organization
Project adminFull project settings, members, repos, and PM work
Project memberTasks, views, agents, and repos allowed by effective policy
Team viewer (team-scoped)Read-only access to team-linked projects, when granted
Note

Projects belong to your organization. Org admins can see all projects; members see the ones they're added to. Archiving a project does not delete tasks or audit history — it removes the project from default directories.

Start from a template

Larger orgs often create a planned project from a template: default views ("My work", "Blocked", "This cycle"), label set, and a standing integration checklist. Clone the pattern rather than reinventing structure for every initiative.