Projects

Create isolated workspaces tied to git repositories, each with its own tickets, notes, memory, and configuration.

What Is a Project

A project in AgentsInFlow is a local git repository registered as a workspace. Each project is completely isolated — its tickets, folders, notes, memory records, and configuration never leak into other projects.

Think of a project as the boundary around a single codebase. Everything you do inside AgentsInFlow — creating tickets, running executions, chatting with assistants — happens within the context of the active project.

Scope	What It Contains
Tickets	Kanban board, ticket types, priorities, and statuses
Executions	Terminal sessions, engine runs, and their output
Notes	Rich-text notes organized in folders
Memory	Decisions, procedures, principles, and preferences
Git state	Branches, worktrees, commit history
Configuration	Default engine, model, and project-level settings

Creating a New Project

There are two ways to create a project: from the sidebar rail or during first-run onboarding.

From the sidebar

Click the + button at the bottom of the sidebar rail.

A system folder picker opens. Navigate to the root of your git repository and select it.

Choose your preferred default engine (Claude Code, Codex, or Cursor).

The project appears in the sidebar rail and becomes the active workspace.

[Screenshot: sidebar rail with + button highlighted at the bottom]

The selected folder must be a git repository (contain a .git directory). AgentsInFlow uses git for branching, worktrees, and version control features.

Linking Git Repositories

When you create a project, AgentsInFlow reads the git state of the selected folder. This connection enables several integrated features:

Branch tracking — the Git view shows the current branch, recent commits, and changed files.
Worktree branching — executions can run in isolated git worktrees so parallel work never conflicts. See Branching & Worktrees.
Diff review — after an execution completes, review the exact changes the agent made.
AIF directory — AgentsInFlow stores its runtime data in a .aif/ folder at the repository root.

[Screenshot: Git view panel showing branch name, recent commits, and changed files]

Each project is linked to exactly one git repository. If you need to work on multiple repos, create a separate project for each one.

Switching Projects

The sidebar rail on the left edge of the window lists all registered projects. Each project is represented by an icon showing the first letter of its name.

[Screenshot: sidebar rail showing multiple project icons with one highlighted as active]

Click to switch

Click any project icon in the sidebar rail. The entire workspace context changes immediately — the Kanban board, notes, Git view, and terminals all reflect the selected project.

Active indicator

The currently active project has a highlighted border on its icon. Hovering over any project icon shows a tooltip with the full project name and path.

Reordering

Drag and drop project icons in the sidebar rail to reorder them. Your preferred order persists across app restarts.

Switching projects does not close running terminals or executions. Background work continues; you can switch back anytime to check progress.

Project Settings

Right-click a project icon in the sidebar rail and select Settings to open the project settings panel.

[Screenshot: project settings panel showing name, path, default engine, and model dropdowns]

Setting	Description
Project name	Display name shown in the sidebar rail and throughout the UI
Path	Absolute path to the git repository root (read-only after creation)
Default engine	Engine pre-selected when launching new executions (Claude Code, Codex, or Cursor)
Default model	Model pre-selected for the default engine. See Engine & Model Config
Remove project	Unregisters the project from AgentsInFlow. Does not delete files on disk

Project-Level Configuration

Beyond the settings panel, projects store runtime configuration in the .aif/ directory at the repository root. This directory is created automatically when you register the project and contains:

Path	Purpose
`.aif/config.json`	Project configuration including plugins and feature flags
`.aif/AIF.md`	Runtime contract loaded by every engine session — defines rules, CLI paths, and activation policies
`.aif/memory/`	Project-scoped memory records (decisions, procedures, principles)
`.aif/instructions/`	Domain-specific instruction files (tickets, execution, diagrams, etc.)
`.aif/worktrees/`	Git worktrees created for isolated execution branches

The AIF runtime contract

The .aif/AIF.md file is injected into every engine session. It tells the AI agent where to find CLIs, which rules to follow, and how to interact with the project's tooling. You can edit this file to customize agent behavior project-wide.

[Screenshot: .aif/ directory structure in a file tree showing config.json, AIF.md, memory/, and instructions/]

Engine-specific configuration files

In addition to the .aif/ directory, each engine may read its own config files from the repository:

AGENTS.md and .claude/CLAUDE.md — project instructions for Claude Code sessions
.cursorrules — project instructions for Cursor sessions
codex.md — project instructions for Codex sessions

AgentsInFlow respects these files and passes them to the respective engine during execution. For engine-specific options, see Engine & Model Config.

Managing Projects

Renaming a project

Open project settings and edit the project name. The change is reflected immediately across the sidebar rail and all UI labels.

Removing a project

In project settings, click Remove Project. This unregisters the project from AgentsInFlow but does not delete the repository or any files on disk. The .aif/ directory remains in the repository until you manually remove it.

Removing a project deletes all its tickets, notes, and memory from the AgentsInFlow database. This action cannot be undone. Back up important work before removing.