Skip to content
Tarsk

Project Settings

Project Settings configure a single repository. With a project selected, open them via:

  • The Settings icon in the chat header, or
  • ⋯ More options → Settings in the chat header, or
  • Settings → Project → Settings in the settings overlay

Click Save when done — this closes settings and returns you to the chat view.

Where Settings Live

Section titled “Where Settings Live”

Tarsk stores project settings, including the name, scripts, commit method, commands, and disabled tools, in its local database on this machine. They are not written into the repository, so they are not shared with teammates or restored by a fresh clone.

If an earlier version of Tarsk left a .agents/tarsk-project.json file in a project, Tarsk imports it into the database once on first launch and then ignores it. Editing that file no longer changes anything, and you can delete it or leave it in the repository.

Settings Reference

Section titled “Settings Reference”

Name

Section titled “Name”

The display name shown on the projects home grid and project landing page. Changing the name does not affect the repository or any workspace directories.

Project Icon

Section titled “Project Icon”

Pick an image to show as the project icon. Tarsk scales it to a 256x256 PNG and stores it in the local database for this machine. It is not written into the repository.

Setup Script

Section titled “Setup Script”

A shell command that runs automatically in a new workspace’s directory immediately after the workspace is created (i.e. after the clone completes).

Examples:

Terminal window
npm install
bun install
pip install -r requirements.txt
cargo build
bundle install

The script runs in the workspace’s working directory. If it fails, the workspace is still created but a warning is shown. Leave this blank if no initial setup is needed.

The sparkle button works the script out for you: a model reads the repository’s manifests and lockfiles and returns the install commands, falling back to lockfile detection when no model is available. Nothing is written until you save.

Run Command

Section titled “Run Command”

The command used by the Run/Stop button in the chat header to start your development server. The sparkle button fills it in: Tarsk uses a dev or start script the project already declares, and otherwise asks a model to infer one from the repository contents.

Examples:

Terminal window
bun dev
npm run dev
python manage.py runserver
rails server

Tarsk runs one dev server per project, using a workspace’s working directory. See Dev Server for details.

The project landing page also shows Start App when a run command is configured and the server is not running.

Both sparkle buttons run with the model you last used on the project, or the Default model alias. When nothing can be inferred, Tarsk says why instead of filling in a guess.

Custom Commands

Section titled “Custom Commands”

Define reusable shell commands for the project from the commands dialog (the commands button in the chat header). Each command has a name, a lucide icon, a shell command, and an optional working folder relative to the project root.

Commands are stored in the local database next to the other settings and apply to every workspace of the project on this machine.

Commit Method

Section titled “Commit Method”

Controls how the Git Ops button handles finished work:

MethodBehaviour
Pull RequestsFeature branches and pull request workflow via the gh CLI
Direct CommitsCommit to the current branch; the Git Ops dropdown hides PR creation

The gh CLI must be installed and authenticated for pull request mode. See cli.github.com.

Built-in Browser

Section titled “Built-in Browser”
SettingBehaviour
OnShows the Browser panel in the chat dock; detected dev URLs open inside Tarsk (default)
OffHides the Browser panel; detected dev URLs open in your system browser

Outside the desktop app (the web and mobile builds) a detected dev URL always opens in your system browser, whatever this setting says.

See Browser Preview.

Environment Variables

Section titled “Environment Variables”

Under Variables in settings:

  • Add key/value pairs injected into the agent’s shell environment for all workspaces
  • Values are stored encrypted locally
  • Variable names are normalized to uppercase
  • Existing values are masked; leave the value field blank to keep the current value

Plugin Settings

Section titled “Plugin Settings”

System Prompt

Section titled “System Prompt”

Under Plugins → System Prompt, toggle between the generated system prompt (built from AGENTS.md, rules, skills) and a custom prompt you write yourself. When custom is enabled, the agent uses your text instead of the auto-generated one.

Tools

Section titled “Tools”

Under Plugins → Tools, enable or disable built-in agent tools per project. Disabled tools are hidden from the agent in every workspace. Disabling MCP blocks every MCP server tool for the project.

See Chat for the full tool list.

Deleting a Project

Section titled “Deleting a Project”

Use Danger Zone → Delete Project. This section is always available. The confirmation dialog says “This will remove the project and all its data” and does not list workspaces. Deletion cannot be undone.

On the projects home grid, a project’s trash icon appears only when the project has no threads. Projects with threads can only be deleted from Project Settings.

If the project folder lives outside the Tarsk data directory (for example, a project connected via Open Folder), Tarsk only unregisters the project. The folder and its contents stay on disk.

Section titled “Related”