{
  "mcpServers": {
    "terminal-use": {
      "command": "npx",
      "args": ["-y", "terminal-use-mcp"],
      "env": {
        "TERMINAL_USE_WORKSPACE_ROOT": "<your-project-path>",
        "TERMINAL_USE_ALLOWED_CWD": "<your-project-path>,/tmp"
      }
    }
  }
}

{
  "mcpServers": {
    "terminal-use": {
      "command": "npx",
      "args": ["-y", "terminal-use-mcp"],
      "env": {
        "TERMINAL_USE_WORKSPACE_ROOT": "<your-project-path>",
        "TERMINAL_USE_ALLOWED_CWD": "<your-project-path>,/tmp"
      }
    }
  }
}

{
  "mcp": {
    "terminal-use": {
      "type": "local",
      "command": ["npx", "-y", "terminal-use-mcp"],
      "enabled": true,
      "environment": {
        "TERMINAL_USE_WORKSPACE_ROOT": "<your-project-path>",
        "TERMINAL_USE_ALLOWED_CWD": "<your-project-path>,/tmp"
      }
    }
  }
}

Set up terminal-use-mcp with these steps:

1. Prerequisites check:
   - Confirm Node.js 18+ and npm 8+ are available (node -v / npm -v)

2. Configure MCP:
   - Create or edit .mcp.json in the project root, adding:
     {
       "mcpServers": {
         "terminal-use": {
           "command": "npx",
           "args": ["-y", "terminal-use-mcp"],
           "env": {
             "TERMINAL_USE_WORKSPACE_ROOT": "<current-project-absolute-path>",
             "TERMINAL_USE_ALLOWED_CWD": "<current-project-absolute-path>,/tmp"
           }
         }
       }
     }
   - Replace <current-project-absolute-path> with the actual path

3. Restart Claude Code for the config to take effect

4. Verify:
   - Confirm terminal.health, terminal.start etc. appear in the MCP tool list
   - Call terminal.health to confirm server and provider status are OK
   - If tools are not visible, check .mcp.json formatting and restart again

Constraints:
- Do not output any secrets
- Only notify me if node-pty compilation fails; handle other issues yourself

Set up terminal-use-mcp with these steps:

1. Prerequisites check:
   - Confirm Node.js 18+ and npm 8+ are available (node -v / npm -v)

2. Configure MCP:
   - Edit the Claude Desktop config file:
     - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     - Windows: %APPDATA%\Claude\claude_desktop_config.json
   - Add to mcpServers:
     "terminal-use": {
       "command": "npx",
       "args": ["-y", "terminal-use-mcp"],
       "env": {
         "TERMINAL_USE_WORKSPACE_ROOT": "<current-project-absolute-path>",
         "TERMINAL_USE_ALLOWED_CWD": "<current-project-absolute-path>,/tmp"
       }
     }
   - Replace <current-project-absolute-path> with the actual path

3. Fully quit and restart Claude Desktop

4. Verify:
   - Confirm terminal.health and similar tools appear in conversation
   - Call terminal.health to confirm server status is OK
   - If tools are not visible, check config file JSON format and path spelling

Constraints:
- Do not output any secrets
- Only notify me if node-pty compilation fails or config file cannot be found

Set up terminal-use-mcp with these steps:

1. Prerequisites check:
   - Confirm Node.js 18+ and npm 8+ are available (node -v / npm -v)

2. Configure MCP:
   - Add to .opencode/opencode.json in the mcp field:
     {
       "type": "local",
       "command": ["npx", "-y", "terminal-use-mcp"],
       "enabled": true,
       "environment": {
         "TERMINAL_USE_WORKSPACE_ROOT": "<current-project-absolute-path>",
         "TERMINAL_USE_ALLOWED_CWD": "<current-project-absolute-path>,/tmp"
       }
     }
   - Replace <current-project-absolute-path> with the actual path

3. Restart OpenCode for the config to take effect

4. Verify:
   - Confirm terminal.health, terminal.start etc. appear in the MCP tool list
   - Call terminal.health to confirm server and provider status are OK
   - If tools are not visible, check .opencode/opencode.json formatting and restart again

Constraints:
- Do not output any secrets
- Only notify me if node-pty compilation fails; handle other issues yourself

sudo, su, ssh, scp, sftp, rm, dd, mkfs,
shutdown, reboot, chmod, chown, curl, wget,
nc, ncat, telnet

// Environment variable overrides
TERMINAL_USE_ALLOW_COMMANDS=git,make    // additional allow
TERMINAL_USE_DENY_COMMANDS=node,python3  // additional deny
TERMINAL_USE_RISKY_COMMAND_MODE=deny     // deny | ask | allow

// Allowed by default
const allowedCwdRoots = [
  process.cwd(),
  process.env.TERMINAL_USE_WORKSPACE_ROOT,
  ...splitCsv(process.env.TERMINAL_USE_ALLOWED_CWD),
]

// Denied by default (unless under an allowedCwdRoots subtree)
const deniedCwdRoots = ["/", "/root", "/home", "/etc", "/usr", "/var", "/sys", "/proc", "/boot"]

const SECRET_PATTERNS = [
  /ghp_[0-9a-zA-Z]{36}/g,           // GitHub PAT
  /sk-[a-zA-Z0-9]{20}T3BlbkFJ.+/g,  // OpenAI key
  /sk-ant-[a-zA-Z0-9-]+/g,          // Anthropic key
  /(?:AKIA|ABIA|ACCA|ASIA)[0-9A-Z]{16}/g,  // AWS key
  /Bearer\s+[a-zA-Z0-9\-._~+/]+=*/g,      // Bearer token
  /-----BEGIN .* PRIVATE KEY----[\s\S]*?-----END .* PRIVATE KEY-----/g,  // Private key block
  /(?<=^|\n)\s*(password|secret|token|api_key)\s*=\s*.+/gi,  // .env style
]

const CONFIRMATION_PATTERNS = [
  /\bapprov[ei]\b/i, /\ballow\b/i, /\bconfirm\b/i,
  /\boverwrite\b/i, /\bdelete\b/i, /\bpassword\b/i,
  /\[y\/n\]/i, /\[Y\/n\]/i,
  /\bAllow command\??/i, /\bRun command\??/i,
]

{ observationTrust: "untrusted" }

{
  "hosts": {
    "devbox": {
      "host": "192.168.1.20",
      "port": 22,
      "username": "hlh",
      "auth": {
        "type": "agent"
      },
      "knownHosts": "~/.ssh/known_hosts",
      "defaultCwd": "/home/hlh/dev",
      "remoteAllowedCwd": [
        "/home/hlh/dev",
        "/srv/lab"
      ],
      "remoteDeniedCwd": [
        "/",
        "/root",
        "/etc",
        "/boot",
        "/proc",
        "/sys"
      ],
      "allowTmux": true,
      "connectTimeoutMs": 10000,
      "keepaliveIntervalMs": 15000
    }
  }
}

# Start ssh-agent
eval "$(ssh-agent -s)"

# Add key
ssh-add ~/.ssh/id_ed25519

# Confirm loaded
ssh-add -l

type SshAuthRef =
  | { type: "agent"; socket?: string }
  | { type: "key-file"; path: string; passphraseEnv?: string }

// V2: Start remote TUI
terminal.start({
  provider: "ssh-pty",
  target: { kind: "ssh", profile: "devbox" },
  command: "lazygit",
  cwd: "/home/hlh/dev/project"
})

// V2: Verify target before starting
terminal.verify_target({ profile: "devbox" })
// → { ok: true, hostFingerprint: "SHA256:...", remote: { tmuxAvailable: true, ... } }

// V2: List available targets
terminal.targets({})
// → { targets: [{ kind: "local", name: "local" }, { kind: "ssh", profile: "devbox", ... }] }

type TerminalSnapshot = {
  sessionId: string
  screen: string
  cursor: { x: number; y: number }
  cols: number
  rows: number
  status: "starting" | "running" | "exited" | "killed" | "error"
  changed?: boolean
  exitCode?: number | null
  title?: string
  isFullscreen?: boolean
  highlights?: Array<{
    row: number
    colStart: number
    colEnd: number
    text: string
    kind: "inverse" | "selection" | "active" | "unknown"
  }>
  riskSignals?: Array<{
    type: "confirmation_prompt" | "credential_prompt" | "destructive_prompt" | "external_agent_permission"
    text: string
    severity: "low" | "medium" | "high"
  }>
  timestamp: string
  observationTrust: "untrusted"
}

type ToolError = {
  ok: false
  error: {
    code: TerminalUseErrorCode
    message: string
    provider?: string
    sessionId?: string
    retryable: boolean
    hint?: string
    details?: unknown
  }
}

type TerminalUseErrorCode =
  | "SESSION_NOT_FOUND"
  | "PROVIDER_NOT_AVAILABLE"
  | "PROVIDER_CAPABILITY_UNSUPPORTED"
  | "SESSION_TIMEOUT"
  | "UNSAFE_COMMAND"
  | "LARGE_PASTE_REFUSED"
  | "SECRET_DETECTED"
  | "CONFIRMATION_REQUIRED"
  | "SESSION_BUSY"
  | "PROCESS_EXITED"
  | "DEPENDENCY_MISSING"
  | "INVALID_CWD"
  | "INVALID_MOUSE_COORDS"
  | "INVALID_KEY"
  | "INTERNAL_ERROR"
  // V2 additions (design phase)
  | "SSH_PROFILE_NOT_FOUND"
  | "SSH_HOST_KEY_MISMATCH"
  | "SSH_HOST_KEY_UNKNOWN"
  | "SSH_AUTH_FAILED"
  | "SSH_CONNECT_TIMEOUT"
  | "SSH_CONNECTION_LOST"
  | "SSH_INLINE_TARGET_DENIED"
  | "REMOTE_CWD_DENIED"
  | "REMOTE_TMUX_NOT_AVAILABLE"
  | "REMOTE_COMMAND_DENIED"

type TerminalTarget =
  | { kind: "local" }
  | {
      kind: "ssh"
      profile?: string
      host?: string
      port?: number
      username?: string
      auth?: SshAuthRef
      knownHostPolicy?: "strict"
    }