Auto Suno Agent

Chrome extension plus native host that runs an agent workflow to turn a user prompt into a Suno song.

Architecture

• WXT runs the Chrome extension shell and side panel UI.
• LangGraph.js runs the workflow graph: prompt planning, Suno execution, and summary.
• Playwright attaches to a real Chrome debug session with connectOverCDP() to automate Suno reliably.
• SQLite stores run history, workflow steps, selector attempts, and basic site-memory records.
• Model access is provider-pluggable:
  • local Ollama
  • any OpenAI-compatible endpoint with your own API key and model name

Why this stack

For March 2026, this is the most practical combination:

• A pure extension-only DOM bot is weaker than CDP automation for dynamic Suno flows.
• A pure Playwright app is weaker than an extension for in-browser controls and user-owned settings.
• LangGraph.js gives you an existing workflow agent runtime instead of a custom loop.

Setup

Use Node 20.19+ or 22+ for the cleanest WXT/Vite experience. This repo built successfully on 20.18.1 in this environment, but it emitted engine warnings.

1. Install dependencies.

npm install

2. Start Chrome in debug mode and sign into Suno in that Chrome window.

Example on Linux:

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.config/auto-suno-chrome"

Or use the helper:

npm run launch:chrome

3. Verify the Chrome debug endpoint.

npm run check:chrome -- http://127.0.0.1:9222

4. Run the extension in dev mode.

npm run dev

5. Load the unpacked extension from .output/chrome-mv3/ in chrome://extensions.

6. Copy the extension ID from chrome://extensions and install the native host manifest.

npm run install:native-host -- --extension-id YOUR_EXTENSION_ID

7. In the extension side panel:
   • choose Ollama or OpenAI Compatible
   • set your model name
   • add your API key if you are using a hosted endpoint
   • set the Chrome debug URL if it is not http://127.0.0.1:9222

CLI workflow runner

You can also run the workflow directly without the extension UI:

npm run run:workflow -- \
  --prompt "Find the song I made yesterday in my library called Neon Skyline" \
  --chrome-debug-url http://127.0.0.1:9222

Useful options:

• --provider
• --model
• --ollama-base-url
• --openai-base-url
• --api-key
• --auto-submit false
• --poll-seconds 120

Inspecting memory

To inspect the current SQLite memory state:

npm run inspect:db

Supported model modes

Local Ollama

• Base URL: http://127.0.0.1:11434
• Example model: qwen3:30b

Hosted API

• Any OpenAI-compatible chat completions endpoint
• Supply your own base URL, API key, and model string

Current workflow

1. The extension sends the user prompt and provider settings to the native host.
2. The native host classifies the intent and records a new workflow run in SQLite.
3. The planner node either asks the configured model for a structured Suno prompt plan or derives a library-search query for find_song.
4. The executor node attaches to Chrome via CDP and runs the matching subflow:
   • create_song or create_draft: open https://suno.com/create, fill the prompt, optionally submit, and poll
   • find_song: open https://suno.com/library, rank visible matches, try to open the best candidate, and capture detail-page capabilities
5. The workflow records run steps, selector attempts, and observed UI nodes in data/auto-suno.db.
6. The workflow returns a summary and the raw execution payload to the side panel.

Current memory layer

The SQLite database stores:

• runs
• run_steps
• selector_attempts
• ui_nodes
• unknown_requests
• artifacts
• eval_results

This is the first pass of the long-term memory layer. It is designed to migrate cleanly to PostgreSQL later.

Optional snapshots

If you want deeper page-mapping artifacts on top of normal Playwright execution, run the native host with:

AUTO_SUNO_CAPTURE_SNAPSHOTS=1

That stores CDP DOM snapshots and accessibility snapshots as artifacts for visited pages. It is intended for discovery, debugging, and evals, not for every normal run.

Limits

• Google sign-in, MFA, CAPTCHA, and anti-bot checks are still manual.
• The native host installer currently supports Linux and macOS paths. Windows registry registration is not implemented yet.
• Suno selectors may need periodic updates when the site UI changes.