Run your first stack

Install and start

git clone https://github.com/NigelThorne/stack-manager.git
cd stack-manager
npm install
npm start

Open http://127.0.0.1:4310 for the local dashboard. Leave it running.

Add a reviewed config

In your project root, create .stack-manager.config. This example assumes a Git repository with an npm dev command that accepts --port. Install its dependencies in the main checkout first. The worktree shares that installation, so package manifests and lockfiles must match.

export default {
  name: 'my-project',
  ports: { web: { base: 4311, step: 10 } },
  components: {
    web: {
      path: '.',
      worktree: { root: '../project.worktrees', branchPrefix: 'stack/', base: 'HEAD' },
      envFiles: { link: ['node_modules'] },
      command: ['npm', 'run', 'dev', '--', '--port', '{{ports.web}}'],
      ports: { http: 'web' },
      url: 'http://127.0.0.1:{{ports.web}}',
      readiness: { kind: 'http', port: 'web', path: '/', timeoutMs: 120000 }
    }
  }
}

In a second terminal, return to the stack-manager checkout. Run this and the remaining CLI commands there:

npm run cli -- add /path/to/project

Create or run

Choose one option. Create worktrees without starting them, or create and start a new stack in one command. New worktrees use committed files, not uncommitted edits.

npm run cli -- create my-project --name review
# OR create and start a new stack
npm run cli -- up my-project --name review --json

If you chose create, start it with npm run cli -- start review --json. Stop it with npm run cli -- stop review --json. Do not install or change shared dependencies from a linked worktree.