Avaamo Tools

VS Code and Cursor extension wrapper for Avaamo agent workspaces.

Created by Dheeraj Samala.

Developer Experience

After install, the extension adds an Avaamo icon to the Activity Bar. Opening it shows an Account view plus workspace tools for agents, recent local agent workspaces, and grouped actions.

On first use, the developer signs in inside the Avaamo Account view with:

• Avaamo domain
• email address
• Avaamo PIN

The extension uses the normal Avaamo activation-code login flow, opens an Avaamo session, reads the Avaamo access token and CSRF token from the signed-in page, and stores the token plus the session cookie/CSRF pair in VS Code SecretStorage. The Avaamo domain and recent workspace list are stored in VS Code global state. Opening the same editor profile later reuses the stored credentials silently unless the token is invalid.

SSO-only accounts can open the Avaamo login page from the Account view, then paste an Avaamo access token into the same view. Avaamo: Sign In and Avaamo: Set Access Token both focus the Account view instead of opening input prompts.

Developers can then use the Avaamo Activity Bar or command palette to:

• create a new agent from a webview form and pull it into a local workspace
• pull an existing agent by selecting it from the Avaamo agent list
• pull dashboard changes into the current workspace with merge safety
• open a created or selected agent on Avaamo
• open or add the pulled workspace to VS Code/Cursor
• edit the agent files with any IDE or LLM coding assistant
• run status, diff, chat check, serve, regression UI, and docs
• push local changes back to Avaamo
• open the agent on Avaamo from the push success suggestion

Push uses the packaged CLI with --lock --build --yes. If push fails, the extension can run avaamo pull --merge and retry push when there are no conflicts. If conflicts remain, it can use Avaamo AI to draft conflict resolutions, then shows the diff for review before another push. When the developer is already signed in to Avaamo, the extension and packaged CLI can create the AI session from the Avaamo access token through /api/auth/dashboard-token, avoiding a separate proxy OTP prompt.

The command id for IDE chat push integrations is avaamo.push. Codex/Claude-style chat agents should offer Avaamo: Push Changes or Push to Avaamo as a human-clicked action when the chat UI supports command buttons or action chips; they should not run a real push themselves. If a developer asks to merge dashboard changes into local work, they can offer Avaamo: Pull & Merge through command id avaamo.pullMerge.

The extension packages the avaamo CLI as a production dependency:

"dependencies": {
  "avaamo": "file:../dist/avaamo.tgz"
}

During npm run package, the prepare-cli script refreshes ../dist/avaamo.tgz from the parent Avaamo CLI and installs it as a real node_modules/avaamo directory. The generated VSIX does not require a global avaamo install.

When the extension activates, it exposes the packaged CLI to new VS Code/Cursor integrated terminals:

• AVAAMO_CLI_PATH points to the packaged avaamo JavaScript entrypoint
• AVAAMO_CLI_BIN_DIR points to the packaged command shim directory
• the packaged node_modules/.bin directory is prepended to PATH, so avaamo --help works in new integrated terminals

Some IDE chat extensions run shell commands outside VS Code's integrated terminal environment, so they may not see the packaged avaamo command on PATH. For Avaamo workspaces, this extension also writes an ignored workspace-local launcher at ./.avaamo/bin/avaamo and refreshes it on activation. IDE agents should try ./.avaamo/bin/avaamo status when plain avaamo status is not available, or use the Avaamo extension action buttons / Command Palette commands for extension-backed operations.

The extension also writes the signed-in account credentials to a device-local auth cache at ~/.avaamo/dashboard-auth.json with user-only file permissions. The packaged CLI reads that cache only as a fallback when DASHBOARD_ACCESS_TOKEN / DASHBOARD_SESSION_COOKIE are not present, which lets chat-side command runners use ./.avaamo/bin/avaamo debug ... from an extension-opened workspace. Do not inspect, print, or copy that cache; refresh or switch the account from the Avaamo Account panel if auth-required commands fail.

Pulled agent workspaces also include AGENTS.md, CODEX.md, Cursor/Cline/Copilot instruction files, and avaamo-bot-project.json. Those generated files tell IDE assistants such as Codex, Claude, Cursor, Cline, and Copilot how to locate the packaged CLI, which commands they may run for inspection, how to ask a human to create or pull agents, how to fetch dashboard diagnostics such as errors, conversation history, single-conversation bundles, and realtime LLM events, how to generate/run regression CSVs, and how to offer human-clicked Avaamo action buttons for supported extension commands without running deploy or other human-explicit actions automatically.

Local Development

cd avaamo/vscode-extension
npm run prepare-cli
npm install
code .

Run the extension host from VS Code with the normal extension debugging flow.

When running from this source folder without node_modules/avaamo, the extension falls back to ../bin/avaamo.js.

Package

cd avaamo/vscode-extension
npm run package:install-deps

If dependencies are already installed, npm run package is enough.

cd avaamo/vscode-extension
npm run package

npm run package runs npm run prepare-cli before vsce package.

Install the generated .vsix in VS Code or Cursor.

Commands

• Avaamo: Sign In
• Avaamo: Sign Out
• Avaamo: Refresh
• Avaamo: Create Agent
• Avaamo: Pull Agent
• Avaamo: Pull & Merge
• Avaamo: Open Agent on Avaamo
• Avaamo: Push Changes
• Avaamo: Status
• Avaamo: Diff
• Avaamo: Push Dry Run
• Avaamo: Chat Check
• Avaamo: Serve Workspace
• Avaamo: Open Regression UI
• Avaamo: Resolve Merge Conflicts with AI
• Avaamo: Show CLI Docs
• Avaamo: Set Access Token
• Avaamo: Clear Access Token

Avaamo: Open Regression UI starts the packaged CLI's local regression server in the background and embeds it in a center editor panel. The panel includes an Open externally button for opening the same local UI in the system browser.

Avaamo tokens, session cookies, and CSRF tokens are stored in VS Code SecretStorage and passed to the packaged CLI for extension-launched commands.