Projects

Projects are the central unit of work in RedStick AI. Each project has a workspace directory, framework configuration, and associated tasks.

Creating a Project#

Click New Project from the dashboard to open the 5-step wizard:

1. Identity — Project name and optional description. The system auto-generates a URL-friendly slug from the name (3–63 characters, lowercase letters, numbers, and hyphens). The slug is immutable after creation.
2. Stack — Framework, runtime version, startup command, and install command.
3. Source — Optional Git clone URL and default AI provider/model.
4. Services — Optional backing services (e.g., PostgreSQL, Redis) to provision at creation time.
5. Review — Summary before submission.

Permission required: project:create

Supported Frameworks#

15 frameworks across 4 display categories (frontend, backend, fullstack, other):

Each framework provides specific agent instructions that guide the AI on conventions, entry points, and best practices.

Runtime Versions#

Projects can select a specific runtime version for their framework's language. If not specified, the default version is used.

The none framework does not support runtime version selection.

Dashboard#

The project dashboard shows all projects with their status:

• Execution counts (running / completed / failed) per project — shown on pinned project cards only; regular project cards show a live status badge only when a run is actively in flight
• Pin/unpin projects for quick access in the sidebar
• Archive/unarchive — Hide projects without deleting them (archive requires project:delete permission; unarchive requires project:settings)
• Filter to include or exclude archived projects

Project Settings#

Access settings via Settings in the project card menu or the gear icon inside a project. The settings page has four tabs:

General tab#

• Project Name and Description
• Framework (can be changed) and Runtime Version
• Startup Command — Overrides the framework's default preview command
• Install Command — Custom dependency installation command
• Default Provider / Model — AI provider and model override for this project
• Plan-mode behaviour — Always plan / Never plan / Auto (see plan-mode.md)

Semantic code index

The General tab includes a Semantic index widget that controls ChromaDB vector indexing for the project's workspace. The index enables semantic code search used by the planner for context injection.

States: idle · indexing · complete · error

Actions (require project:settings):

• Build index — starts a full index from scratch (only available in idle state)
• Re-index — rebuilds the index when it is complete
• Cancel — cancels an in-progress index and resets it to idle
• Retry — retries after an error
• Delete index — permanently drops the ChromaDB collection and status record; the index can be rebuilt at any time

While indexing, the widget shows a progress bar with file counts and the current phase/path.

Automatic indexing: when a project is created with a non-empty workspace (e.g., cloned from a Git URL), a full index is triggered automatically. Incremental updates also run automatically after each agent run completes.

Git tab#

Git configuration for the project's workspace repository.

Environment tab#

Project-scoped environment variables (config vars) injected into agent runs.

MCP Servers tab#

Model Context Protocol server configuration for this project.

Permission required: project:settings

Deleting a project#

A project must be archived first before it can be deleted. Once archived, a Delete option appears in the project card menu on the dashboard. Deletion is permanent and removes the project, execution history, and the workspace directory on disk. Billing usage records (usage_events) are retained for audit purposes — their execution references are nulled out, but tenant and subscription totals are preserved.

Permission required: project:delete

Project context (AGENTS.md)#

Use the file browser to edit the context file that is injected into every agent task. The worker reads context files from the workspace root using this priority order:

1. .redstickai/agents.md
2. AGENTS.md
3. CLAUDE.md

The first file found wins. AGENTS.md at the workspace root is the recommended convention. CLAUDE.md is honored as a fallback for repositories that already use it. Files larger than 8 KB (8192 bytes) are ignored; keep context files concise.

Use the context file to:

• Set project-specific coding conventions
• Define architecture decisions
• Specify allowed tool paths
• Provide domain context

The file editor includes an optional auto-save toggle. In addition to your context file, a per-task append-only progress log is injected alongside it on every run, giving the worker continuity across retries and follow-up turns.

Archiving#

Archive projects you're not actively working on. Archived projects:

• Don't appear in the default dashboard view
• Retain all data and task history
• Can be unarchived at any time
• Cannot start new tasks while archived

Archival guards:

• Cannot archive a project while any run is in an active state (pending, running, awaiting approval, awaiting user, or awaiting user input) — stop or wait for them to complete first
• Any queued runs are automatically cancelled when the project is archived
• If a queued run is dequeued after archival (race condition), it is cancelled instead of started