.carryon.json

A .carryon.json file defines the terminal sessions that belong to a project. Place it in the root of your repository so that carryOn - and your team - can spin up a consistent set of terminals with a single command.

Basic example

{
  "version": 1,
  "terminals": [
    { "name": "api" },
    { "name": "frontend", "command": "npm run dev" }
  ]
}

This configuration defines two terminals. The api terminal opens a plain shell; the frontend terminal opens a shell and immediately runs npm run dev.

Split groups

Wrap terminals in an array to open them as a split group in VS Code. The first terminal in the group is the primary pane; the rest split beside it.

{
  "version": 1,
  "terminals": [
    { "name": "server", "command": "npm run dev", "color": "green" },
    [
      { "name": "tests", "command": "npm test -- --watch", "color": "yellow" },
      { "name": "logs", "command": "tail -f app.log", "color": "cyan" }
    ]
  ]
}

This creates one standalone terminal (server) and a split group with tests and logs side by side. Each terminal gets a colored tab icon for quick identification.

Full schema

{
  "version": 1,
  "terminals": [
    {
      "name": "api",
      "command": "go run ./cmd/server",
      "backend": "native",
      "cwd": "server",
      "shell": "/bin/zsh",
      "color": "green"
    },
    [
      {
        "name": "frontend",
        "command": "npm run dev",
        "cwd": "web",
        "color": "cyan"
      },
      {
        "name": "storybook",
        "command": "npm run storybook",
        "cwd": "web",
        "color": "magenta"
      }
    ]
  ]
}

Top-level fields

Field	Type	Required	Description
version	number	yes	Schema version. Always 1.
terminals	array	yes	List of terminal entries. Each entry is either a terminal object or an array of terminal objects (split group).

Terminal fields

Field	Type	Required	Description
name	string	yes	Name for the session. Must be unique within the file.
command	string	no	Command to run after the shell starts. If omitted, the terminal opens an interactive shell.
backend	string	no	Backend to use for this terminal (native or tmux). Defaults to the value of default.backend in your config.
cwd	string	no	Working directory for the terminal, relative to the location of .carryon.json. If omitted, the directory containing .carryon.json is used.
shell	string	no	Path to the shell executable. If omitted, the user’s default shell is used.
color	string	no	Tab icon color in VS Code. One of: black, red, green, yellow, blue, magenta, cyan, white, brightBlack, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite.
icon	string	no	Tab icon in VS Code. Any VS Code ThemeIcon name, e.g. flame, database, globe, beaker.

CLI usage

Initialize a project

Generate a starter .carryon.json in the current directory:

carryon project init

Start project terminals

Create and attach to all the terminals defined in .carryon.json:

carryon project terminals

Each terminal entry becomes a carryOn session. If a session with the same name already exists, it is reused rather than recreated.

Associate and disassociate

You can manually associate the current directory with a set of running sessions, or remove that association:

# Associate the current directory with its project sessions
carryon project associate

# Remove the project association
carryon project disassociate

VS Code integration

The VS Code extension detects .carryon.json automatically when you open a workspace. If the carryon.autoOpenTerminals setting is enabled, the extension starts all defined terminals when the project opens.

Tips

• Check it into version control. A .carryon.json file is meant to be shared. Your whole team gets the same terminal layout with zero manual setup.
• Use command for long-running processes. Dev servers, watchers, and log tails are ideal candidates. Interactive shells that do not need a startup command can omit the field.
• Use cwd for subdirectories. In a monorepo, point each terminal at the right package or service directory so commands run in the correct location.