AI Support Agent CLI

A daemon that turns your machine into an AI-powered remote agent. Install it, authenticate via browser, and your team can send shell commands, AI chat prompts, file operations, and more — all from a Web UI, with results streamed back in real time.

┌──────────────┐  AppSync     ┌─────────────────┐  WebSocket/HTTP  ┌──────────────────┐
│   Web UI     │ ──────────── │   API Server    │ ─────────────── │  Agent CLI       │
│  (browser)   │  subscription│   (NestJS)      │  commands/result │  (your machine)  │
└──────────────┘              └─────────────────┘                  └──────────────────┘
                                                                     ├─ Claude Code
                                                                     ├─ Shell / PTY
                                                                     ├─ File I/O
                                                                     ├─ Git repos
                                                                     ├─ MCP server
                                                                     └─ VS Code tunnel

Why?

Remote AI pair-programming — Ask questions about your codebase from the Web UI; Claude Code runs on the agent machine with full repository access.
Multi-tenant, multi-project — A single agent manages multiple projects across different tenants. Add/remove projects on the fly; the agent hot-reloads.
Zero-config realtime — AppSync WebSocket subscriptions deliver commands instantly. No polling delay, no port forwarding.
Secure by default — OAuth login, 0600 config permissions, nonce-protected callbacks, SQL injection detection, path traversal guards, and environment sanitization.

Quick Start

npm install -g @ai-support-agent/cli

# Opens your browser → select tenant & project → done
ai-support-agent login

# Start the daemon (Ctrl-C to stop)
ai-support-agent start

That's it. The agent registers with the server, syncs project config, clones repositories, and starts listening for commands.

Add more projects

ai-support-agent add-project          # browser OAuth flow
ai-support-agent status               # verify registered projects

Run in Docker

ai-support-agent start --docker

Project dirs, ~/.claude/, and ~/.aws/ are auto-mounted. The container runs with your host UID/GID.

Run as a background service

ai-support-agent service install      # install as a system service
ai-support-agent service start        # start the service
ai-support-agent service status       # check service status
ai-support-agent service stop         # stop the service
ai-support-agent service restart      # restart the service
ai-support-agent service uninstall    # remove the service

How It Works

Register — Agent sends its capabilities (shell, file I/O, chat, terminal, vscode) to the API.
Subscribe — Connects to AppSync for real-time command delivery.
Config sync — Pulls project settings, MCP config, and repo list from the server.
Execute — Receives commands, runs them locally, streams results back chunk-by-chunk.

Each project runs in its own forked child process. The main process watches config.json and hot-adds/removes projects without restart.

Supported Commands

Command Type	What It Does
`chat`	Runs Claude Code (or Anthropic API) with your codebase context
`execute_command`	Executes a shell command with timeout and output capture
`file_read` / `file_write` / `file_list` / `file_rename` / `file_delete` / `file_mkdir`	File system operations
`process_list` / `process_kill`	Process management
`chat_cancel`	Cancels a running chat process
`e2e_test`	End-to-end test execution with Playwright browser automation and step reporting
`setup` / `config_sync` / `reboot` / `update`	Lifecycle management

Chat Modes

Mode	How it works
`claude_code` (default)	Spawns Claude Code CLI as a subprocess with MCP tools, system prompts, and tool allowlists
`api`	Direct Anthropic API streaming. Requires `ANTHROPIC_API_KEY`

The mode is resolved as: agent config → server default → auto-detection (whether claude CLI is installed).

Built-in MCP Server

The agent ships a Model Context Protocol server that Claude Code can call:

General tools:

Tool	Description
`get_credentials`	Fetch AWS STS or database credentials from the API
`db_query`	Run SELECT queries (injection-protected)
`get_db_schemas`	Retrieve table/column metadata
`file_upload`	Upload files to S3 via presigned URLs
`get_project_info`	Fetch project configuration
`read_conversation_file`	Read conversation history

Browser automation tools (Playwright-based):

Tool	Description
`browser_navigate`	Navigate to a URL and take a screenshot
`browser_click`	Click an element by CSS selector
`browser_fill`	Fill a form field with a value
`browser_get_text`	Extract text from a specific element
`browser_login`	Log in using saved credentials
`browser_extract`	Extract text and save to a session variable atomically
`browser_set_variable` / `browser_get_variable` / `browser_list_variables`	Manage session variables
`browser_close`	Close the browser session

E2E test tools:

Tool	Description
`report_test_step`	Report an E2E test step result (status, screenshot, duration) to the API

CLI Reference

ai-support-agent <command> [options]

Commands:
  start              Start the agent daemon
  login              Authenticate via browser OAuth
  add-project        Add a project (browser OAuth)
  remove-project     Remove a project by code
  configure          Register with --token and --api-url
  status             Show agent status and registered projects
  set-language       Set display language (en | ja)
  set-auto-update    Configure auto-update (--enable | --disable | --channel)
  set-project-dir    Set project working directory
  docker-login       Login and start in Docker
  service            Manage agent background service

Global options:
  --lang <lang>      Override display language for this invocation
  --version          Show version

`service` Subcommands

service install     Install the agent as a system background service
service uninstall   Uninstall the agent service
service start       Start the agent service
service stop        Stop the agent service
service restart     Restart the agent service
service status      Show service status

Options (install):
  --verbose          Show detailed installation info
  --no-docker        Install in native mode (skip Docker)

`start` Options

--verbose                  Enable debug logging
--heartbeat-interval <ms>  Heartbeat interval (default: 60000)
--no-auto-update           Disable auto-update for this session
--update-channel <channel> Release channel: latest | beta | alpha
--no-docker                Force native mode (skip Docker)
--docker                   Run inside a Docker container

`set-project-dir` Options

--default <template>       Set default dir template (e.g. ~/projects/{projectCode})
--project <code> --path <path>  Set dir for a specific project

Configuration

Stored at ~/.ai-support-agent/config.json (mode 0600):

{
  "agentId": "macbook-a1b2c3d4",       // auto-generated
  "createdAt": "2025-01-01T00:00:00Z",
  "lastConnected": "2025-06-15T09:00:00Z",
  "language": "en",                     // en | ja
  "agentChatMode": "claude_code",       // claude_code | api
  "defaultProjectDir": "~/.ai-support-agent/projects/{projectCode}",
  "autoUpdate": {
    "enabled": true,
    "autoRestart": true,
    "channel": "latest"                 // latest | beta | alpha
  },
  "projects": [
    {
      "projectCode": "MY_PROJECT",
      "token": "agt_xxxx",
      "apiUrl": "https://api.example.com",
      "projectDir": "~/custom-path"     // optional override
    }
  ]
}

Environment Variables

Variable	Description
`AI_SUPPORT_AGENT_TOKEN`	Override auth token (lowest priority)
`AI_SUPPORT_AGENT_API_URL`	Override API URL (lowest priority)
`AI_SUPPORT_AGENT_CONFIG_DIR`	Override config directory path
`ANTHROPIC_API_KEY`	Required for `api` chat mode
`AI_SUPPORT_E2E_EXECUTION_ID`	E2E test execution ID (set automatically during `e2e_test` runs)
`AI_SUPPORT_E2E_TEST_CASE_ID`	E2E test case ID (set automatically during `e2e_test` runs)

Priority: CLI flags > config file > environment variables.

Project Directory Structure

Each project gets an isolated workspace:

{projectDir}/
├── workspace/
│   ├── repos/          # Git-cloned repositories
│   ├── docs/           # Documentation from server
│   └── artifacts/      # Generated outputs
├── uploads/            # File uploads staging
└── .ai-support-agent/
    ├── cache/          # Temporary cache
    └── aws/            # AWS credential cache

Security

Layer	Detail
Authentication	Browser-based OAuth with localhost callback, CSRF nonce
Config file	Mode `0600`, directory `0700`
Path traversal	Blocked paths: `/root`, `/etc`, `/sys`, `/proc`, `/dev`, `~/.ssh`, `~/.aws`, etc.
SQL injection	Pattern-based detection: comments, time-based blind, encoding bypass, file system access
Subprocess env	Sensitive variables stripped before spawning child processes
File transfer	Extension allowlist (53 types), `basename()` sanitization
Git operations	Branch name validation to prevent CLI injection

Development

git clone https://github.com/mbc-net/ai-support-agent-cli.git
cd ai-support-agent-cli

npm install
npm run dev -- start --verbose    # development mode
npm test                          # run tests
npm run test:cov                  # coverage (95%+ thresholds enforced)
npm run build                     # compile to dist/

Requires Node.js >= 20. node-pty is an optional dependency for terminal/PTY sessions.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 1,025 Commits
.github/workflows		.github/workflows
__mocks__		__mocks__
__tests__		__tests__
docker		docker
src		src
.DS_Store		.DS_Store
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

AI Support Agent CLI

Why?

Quick Start

Add more projects

Run in Docker

Run as a background service

How It Works

Supported Commands

Chat Modes

Built-in MCP Server

CLI Reference

`service` Subcommands

`start` Options

`set-project-dir` Options

Configuration

Environment Variables

Project Directory Structure

Security

Development

License

About

Uh oh!

Releases 253

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

AI Support Agent CLI

Why?

Quick Start

Add more projects

Run in Docker

Run as a background service

How It Works

Supported Commands

Chat Modes

Built-in MCP Server

CLI Reference

service Subcommands

start Options

set-project-dir Options

Configuration

Environment Variables

Project Directory Structure

Security

Development

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 253

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`service` Subcommands

`start` Options

`set-project-dir` Options

Packages