Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"name": "xspace-ai",
"owner": {
"name": "nirholas"
},
"description": "TypeScript SDK and CLI for AI agents that join, listen and speak in X Spaces.",
"plugins": [
{
"name": "xspace-agent-sdk",
"source": "./plugins/xspace-agent-sdk",
"description": "TypeScript SDK and CLI for AI agents that join, listen and speak in X Spaces.",
"category": "automation",
"tags": [
"xspace",
"twitter-spaces",
"voice-agent",
"sdk"
]
}
]
}
Binary file added plugins/xspace-agent-sdk/.claude-plugin/icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 16 additions & 0 deletions plugins/xspace-agent-sdk/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"name": "xspace-agent-sdk",
"version": "0.2.0",
"description": "TypeScript SDK and CLI for AI agents that join, listen and speak in X Spaces.",
"author": {
"name": "nirholas"
},
"repository": "https://github.com/nirholas/xspace-AI",
"homepage": "https://nirholas.github.io/xspace-AI/",
"keywords": [
"xspace",
"twitter-spaces",
"voice-agent",
"sdk"
]
}
67 changes: 67 additions & 0 deletions plugins/xspace-agent-sdk/skills/xspace-agent/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
name: xspace-agent
description: Build and run an AI agent that joins, listens and speaks in X (Twitter) Spaces with the xspace-agent TypeScript SDK or its CLI. Use when the user wants a voice bot in an X Space, with a chosen LLM, speech-to-text and text-to-speech provider.
---

# xspace-agent

`xspace-agent` (npm, version 0.2.0) drives a headless Chromium (Puppeteer) session on x.com, transcribes the Space audio, asks an LLM for a reply and speaks it back. No X API approval is needed, but it logs in with browser cookies.

## Install

```bash
npm install xspace-agent # the SDK
npm create xspace-agent@latest # scaffold a project (create-xspace-agent)
```

The CLI (`packages/cli`, bin `xspace-agent`) is not published to npm. From a clone of the repo run `pnpm install && pnpm build`, then `node packages/cli/bin/xspace-agent <command>`.

## Credentials (environment)

- `X_AUTH_TOKEN` and `X_CT0`: the `auth_token` and `ct0` cookies from a logged-in x.com browser session (preferred). Alternative: `X_USERNAME`, `X_PASSWORD`, `X_EMAIL` (may hit 2FA or CAPTCHA).
- One LLM key: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` or `GROQ_API_KEY`. Voice providers use their own keys, for example `ELEVENLABS_API_KEY`.
- Never print or commit these values. Ask the user to export them in their shell.

## SDK

```ts
import { XSpaceAgent } from 'xspace-agent'

const agent = new XSpaceAgent({
auth: { token: process.env.X_AUTH_TOKEN!, ct0: process.env.X_CT0! },
ai: {
provider: 'openai', // 'openai' | 'claude' | 'groq' | 'gemini' | 'custom'
apiKey: process.env.OPENAI_API_KEY!,
systemPrompt: 'You are a concise, helpful panelist.',
},
voice: { provider: 'elevenlabs', voiceId: 'rachel' }, // optional TTS
browser: { headless: true },
})

agent.on('transcription', ({ text, speaker }) => console.log(`${speaker}: ${text}`))
agent.on('response', ({ text }) => console.log(`Agent: ${text}`))
agent.on('space-ended', () => agent.destroy())

await agent.join('https://x.com/i/spaces/SPACE_ID')
```

Other methods on `XSpaceAgent`: `joinAsListener(url)`, `requestToSpeak()`, `say(text)`, `mute()`, `unmute()`, `leave()`, `destroy()`, `getStatus()`, `setSystemPrompt(prompt)`, `getConversationHistory()`, `getCostSummary()`. Events include `transcription`, `response`, `status`, `error`, `space-ended`.

Middleware hooks run at `before:stt`, `after:stt`, `before:llm`, `after:llm`, `before:tts`, `after:tts` via `agent.use(stage, handler)`; returning null aborts that step.

## CLI (from a clone)

```bash
node packages/cli/bin/xspace-agent init # wizard, writes xspace.config.json
node packages/cli/bin/xspace-agent auth # saves X credentials to .env
node packages/cli/bin/xspace-agent join <url> --provider openai [--listen-only]
node packages/cli/bin/xspace-agent start # run the server with dashboard
node packages/cli/bin/xspace-agent dashboard
```

Global flags: `-c/--config <path>`, `-p/--port <n>`, `-v/--verbose`, `-q/--quiet`, `--no-headless`. `join` also takes `--browser managed|connect`, `--cdp-endpoint <url>` and `--cdp-port <n>`. The URL must contain `x.com/i/spaces/`.

## Notes

- Use `--listen-only` or `joinAsListener` first to confirm transcription before letting the agent speak.
- Only join Spaces where the host allows bots, and tell participants an AI is speaking.
Loading