Projects Overview
A Project in Tarsk represents a single git repository. It is the top-level organisational unit: branches, conversations, commands, and settings all belong to a project.
What a Project Contains
Section titled “What a Project Contains”| Field | Description |
|---|---|
| Name | Display name on the projects home grid |
| Git URL | The remote origin URL used when cloning |
| Path | Local path to the primary (non-branch) clone |
| Branches | Isolated thread workspaces, each a full clone on its own git branch |
| Setup Script | Shell command run automatically after a new branch is created |
| Run Command | Dev server command for the Run/Stop button |
| Commit Method | pull-request or direct |
| Commands | Custom shell commands accessible from the chat header |
| Env Vars | Encrypted environment variables for agent shell sessions |
| Validation Script | Optional command run after each agent response |
The Projects Home Screen
Section titled “The Projects Home Screen”The projects home screen shows an icon grid of connected projects. Click a project icon to open it. A gear icon (top-right) opens app-wide settings. The + menu offers Blank Starter, Git Repo, Open Folder, and New App.
Welcome cards on first launch offer Connect a repo, New App, and Open Folder shortcuts.
Project vs Branch Storage
Section titled “Project vs Branch Storage”The project record in the database stores metadata and configuration. Day-to-day work happens inside branch directories: each branch gets a full independent clone at ~/Library/Application Support/Tarsk/data/{repo-slug}/ (e.g. org-repo from the git URL, with -1, -2 suffixes on conflict).
Next Steps
Section titled “Next Steps”- Create a Project — clone a repo, open a folder, or scaffold a new app
- Project Settings — update name, scripts, and commit method
- Commands — add custom shell commands
- Rules — configure AI agent behavior guidelines
- AGENTS.md — provide branch-level context to the agent