Linked Projects

Cosine uses project links to know which Cosine project a local folder belongs to. This lets commands such as cos deploy, environment builds, and project-aware agent tools work without passing --team and --project every time.

There are two related workflows:

• Initialize the current folder as a Cosine project with cos project init
• Link additional local folders into an active CLI session from the TUI

Initialize an existing folder

If you already have a local project folder and want to use it with Cosine, run:

cos project init

Cosine first tries to detect whether your Git remote already belongs to an existing Cosine project. If it finds one, it links the current folder to that project and saves the selection for future commands.

If no matching Cosine project exists, Cosine creates one and saves it for the current folder.

If the folder does not have a GitHub remote

When cos project init cannot find a GitHub remote, it offers to create one for you:

No GitHub remote was found for this folder.
Create a GitHub repository now? [Y/n]:
Repository name [my-app]:
Visibility (private/public) [private]:
Commit current project and push? [Y/n]:

Every prompt has a default. Press Enter through the prompts to:

1. create a private GitHub repository using the current folder name
2. initialize Git if needed
3. commit the current project if there are local changes
4. push the repository to GitHub
5. create and save the Cosine project link

This uses the GitHub CLI command gh repo create, so you need to have gh installed and signed in with gh auth login.

If you prefer to run the GitHub step yourself, Cosine shows the command to run:

gh repo create my-app --source=. --remote=origin --push --private

Then rerun:

cos project init --force

Non-interactive GitHub setup

If you want the CLI to create the GitHub repository without prompts, use:

cos project init --create-github-repo

By default this creates a private GitHub repository. To choose the visibility explicitly:

cos project init --create-github-repo --github-visibility public

To stage, commit, and push the current project as part of the non-interactive flow:

cos project init --create-github-repo --commit-and-push

After setup completes, Cosine suggests deploying a static site with:

cos deploy

Deploy can run setup for you

If you run cos deploy before the folder has been initialized as a Cosine project, Cosine asks whether to run setup first:

No Cosine project is configured. Run `cos project init` now? [Y/n]:

Press Enter to run the project setup flow, then Cosine continues the deploy.

Use explicit team and project values

You can still bypass saved project detection by passing flags:

cos project init --team my-team --project my-project
cos deploy --team my-team --project my-project dist

Use --force with cos project init to overwrite the saved project selection for the current folder.

Link additional folders in a session

Link additional project directories to give the agent access to multiple codebases in a single session.

Adding a linked project

1. Open the commands menu with / or Ctrl+P
2. Select Link Project
3. Enter the path to the project directory
4. Choose the scope:
   • Session — access lasts until you exit
   • Permanent — saved and restored in future sessions

Once linked, the agent can read and search files across all linked projects. Tools like grep and filename_search accept a directory parameter to target a specific linked project.

When to use linked projects

Use linked projects when:

• a change spans multiple local repositories
• you need the agent to inspect shared libraries alongside an app
• you want one session to reason across related codebases

See Also

• Instant Sites — Deploy a static site after project setup
• Session History — Sessions can be resumed later with their broader context
• Memory — Persist project-specific knowledge across work