Projects
Create web projects, register CLI projects, import from GitHub, and share projects with your team.
Projects are the core unit of work in Stoa. A project represents a codebase or set of files that you want to collaborate on, track decisions for, and build provenance history.
Creating a Web Project
Create a project directly in the browser:
- From the dashboard Projects tab, click "Create web project" (or the "New Project" button if you already have projects).
- Enter a project name (required, max 100 characters).
- Optionally add a description (max 500 characters).
- Optionally share with a team:
- Select a team from the dropdown (shows your role in each team)
- Or leave as "Personal project (not shared)"
- Click Create.
If you create a project from within a team dashboard, the team is pre-selected and the project is automatically shared with all members.
Registering a CLI Project
Bring a local codebase into Stoa:
# Navigate to your project
cd /path/to/your/project
# Initialize tracking
intent init
# Register with the web platform
intent web registerintent web register is org-first: it always creates projects shared with a team. If you belong to multiple teams, use --org to specify which one. If you only have one team, it's selected automatically.
After registration:
- Files sync to the web platform
- You can view and edit files in the browser
- All team members can access the project immediately
Managing CLI Projects
# List all registered projects
intent web projects list
# Show project details
intent web projects show <project-id>
# Share with a team
intent web projects share <project-id> <org-id>
# Remove sharing
intent web projects unshare <project-id>
# Unregister a project
intent web projects delete <project-id>Importing from GitHub
Connect a GitHub repository to browse its code in Stoa:
- Install the Stoa GitHub App on your GitHub organization or personal account.
- Open the GitHub Import dialog from a Space or project view.
- Search repositories by name. Results are grouped by GitHub account.
- Select a repository. Public and private repos are labeled.
- Choose a branch (defaults to the repo's default branch).
- Optionally override the project name.
- Click Import.
Note
Imported GitHub files are read-only by default in Stoa. You can browse and reference them, and the AI agent can use them for context. If you promote a GitHub file into the workspace, it becomes an editable CRDT document, but edits do not sync back to GitHub.
What GitHub Integration Provides
| Feature | Available |
|---|---|
| Browse repository files | Yes |
| View code with syntax highlighting | Yes |
| Use files as AI agent context | Yes |
| Edit files in Stoa | Yes (after promotion to CRDT) |
| Create commits from Stoa | No (planned) |
| Create PRs from Stoa | No (planned) |
| Switch branches after import | No (fixed at import time) |
Projects Table
On the team dashboard, projects are displayed in a sortable, filterable table:
| Column | Description |
|---|---|
| Project | Project name |
| Files | File count |
| Source | Badge showing Web, CLI, or GitHub |
| Created By | Who created the project |
| Created | When the project was created |
| Updated | When files were last updated |
| Space | Which Space the project belongs to |
Click any column header to sort. Click again to reverse the sort direction.
Filtering
Use the filter bar above the table to narrow results:
- Search by project name
- Source dropdown to show only Web, CLI, or GitHub projects
- Space multi-select to filter by Space
- Owner multi-select to filter by creator
Active filters appear as chips below the filter bar. Click a chip to remove it, or use Clear all to reset.
Project Actions
- Open to navigate to the project workspace
- Share to share with a team (or change sharing)
- Remove to unregister the project
Sharing Projects with a Team
When a project is shared with a team:
- All team members can access the project
- The project appears on the team dashboard
- It can be added to Spaces
- Sessions can be created for collaboration
You can share a project:
- At creation time via the "Share With Team" dropdown
- After creation from the project card's Share action
- Via CLI:
intent web projects share <project-id> <org-id>