# Clone the repository
git clone https://github.com/yourusername/terminally-mcp.git
cd terminally-mcp

# Install dependencies (we recommend pnpm for speed!)
pnpm install

# Build the TypeScript code
pnpm build

# Start the MCP server
pnpm start

brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux

# Fedora
sudo dnf install tmux

# Arch
sudo pacman -S tmux

{
  "mcpServers": {
    "terminally-mcp": {
      "command": "node",
      "args": ["/path/to/terminally-mcp/build/index.js"]
    }
  }
}

{
  "terminally-mcp": {
    "command": "node",
    "args": ["/path/to/terminally-mcp/build/index.js"],
    "type": "stdio"
  }
}

// Request
{
  "name": "my-session"  // Optional: custom name for the tab
}

// Response
{
  "window_id": "@1"  // Unique identifier for the created tab
}

// Request
{
  "window_id": "@1",
  "command": "echo 'Hello, World!' && ls -la",
  "timeout": 5000  // Optional: timeout in ms (default: 10000)
}

// Response
{
  "output": "Hello, World!\ntotal 64\ndrwxr-xr-x  10 user  staff  320 Jan 15 10:00 ."
}

// Response
{
  "tabs": [
    {
      "window_id": "@0",
      "name": "default",
      "active": true
    },
    {
      "window_id": "@1",
      "name": "my-session",
      "active": false
    }
  ]
}

// Request
{
  "window_id": "@1",
  "history_limit": 100  // Optional: number of history lines
}

// Response
{
  "content": "$ echo 'Previous command'\nPrevious command\n$ ls\nfile1.txt file2.txt"
}

// Request
{
  "window_id": "@1"
}

// Response
{
  "success": true
}

// Create a new terminal
const tab = await mcp.call('create_tab', { name: 'dev-server' });

// Navigate and start a development server
await mcp.call('execute_command', {
  window_id: tab.window_id,
  command: 'cd /my/project && npm run dev'
});

// Check the output
const output = await mcp.call('read_output', {
  window_id: tab.window_id
});

// Create tabs for different purposes
const webTab = await mcp.call('create_tab', { name: 'web-server' });
const dbTab = await mcp.call('create_tab', { name: 'database' });
const testTab = await mcp.call('create_tab', { name: 'tests' });

// Start services in parallel
await Promise.all([
  mcp.call('execute_command', {
    window_id: webTab.window_id,
    command: 'npm run dev'
  }),
  mcp.call('execute_command', {
    window_id: dbTab.window_id,
    command: 'docker-compose up postgres'
  })
]);

// Run tests
await mcp.call('execute_command', {
  window_id: testTab.window_id,
  command: 'npm test'
});

// Execute multiple commands with proper escaping
await mcp.call('execute_command', {
  window_id: '@1',
  command: `
    echo "Setting up environment..." &&
    export NODE_ENV=development &&
    echo "Installing dependencies..." &&
    npm install &&
    echo "Running migrations..." &&
    npm run migrate &&
    echo "Starting application..." &&
    npm start
  `.trim()
});

terminally-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── services/
│   │   └── tmuxManager.ts    # tmux interaction layer
│   └── tools/
│       ├── definitions.ts    # Tool schemas
│       └── handlers.ts       # Tool implementations
├── test/                     # Test suite
├── build/                    # Compiled JavaScript
└── package.json

# Run in development mode (auto-rebuild)
pnpm dev

# Run tests
pnpm test

# Run tests with UI
pnpm test:ui

# Build for production
pnpm build

# Start production server
pnpm start