> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augent.app/llms.txt
> Use this file to discover all available pages before exploring further.

# spaces

> Download or live-record X/Twitter Spaces audio. Auto-detects live vs ended Spaces. One tool, three modes — start a download, check status, or stop a live recording.

Download or live-record X/Twitter Spaces audio. The tool auto-detects whether a Space is live or ended and handles both. Live Spaces record from the current moment using ffmpeg. Ended Spaces download the full recording via yt-dlp. All downloads run in the background so your agent keeps working.

One tool, three modes based on what parameters you pass:

* **Download**: pass `url` to start a background download
* **Check**: pass `recording_id` to check download status
* **Stop**: pass `recording_id` + `stop: true` to stop a live recording

***

## Example: Download a Space

**Request:**

```json theme={null}
{
  "url": "https://x.com/i/spaces/1yNxaNvaMYQKj"
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "recording_id": "a3f8c21b",
  "mode": "recording",
  "title": "AI Agents and the Future of Automation",
  "url": "https://twitter.com/i/spaces/1yNxaNvaMYQKj",
  "output_dir": "/Users/you/Downloads",
  "pid": 48291,
  "message": "Downloading full recording (ID: a3f8c21b). Use spaces with recording_id to check progress."
}
```

***

## Example: Check status

**Request:**

```json theme={null}
{
  "recording_id": "a3f8c21b"
}
```

**Response (downloading):**

```json theme={null}
{
  "recording_id": "a3f8c21b",
  "status": "downloading",
  "elapsed_seconds": 45,
  "elapsed_formatted": "0m 45s",
  "file": {
    "path": "/Users/you/Downloads/AI_Agents_and_the_Future.m4a",
    "filename": "AI_Agents_and_the_Future.m4a",
    "size_mb": 12.4
  },
  "message": "Still downloading (0m 45s elapsed)"
}
```

**Response (complete):**

```json theme={null}
{
  "recording_id": "a3f8c21b",
  "status": "complete",
  "elapsed_seconds": 83,
  "elapsed_formatted": "1m 23s",
  "file": {
    "path": "/Users/you/Downloads/AI_Agents_and_the_Future.m4a",
    "filename": "AI_Agents_and_the_Future.m4a",
    "size_mb": 47.2
  },
  "message": "Download complete. Saved to /Users/you/Downloads/AI_Agents_and_the_Future.m4a"
}
```

***

## Example: Stop a live recording

**Request:**

```json theme={null}
{
  "recording_id": "a3f8c21b",
  "stop": true
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "recording_id": "a3f8c21b",
  "status": "stopped",
  "elapsed_seconds": 1847,
  "elapsed_formatted": "30m 47s",
  "file": {
    "path": "/Users/you/Downloads/Live_Space_Recording.m4a",
    "filename": "Live_Space_Recording.m4a",
    "size_mb": 22.1
  },
  "message": "Stopped after 30m 47s. Saved to /Users/you/Downloads/Live_Space_Recording.m4a"
}
```

***

## Parameters

| Parameter      | Required | Default       | Description                                                               |
| -------------- | -------- | ------------- | ------------------------------------------------------------------------- |
| `url`          | No       | —             | Twitter/X Space URL. Starts a background download.                        |
| `output_dir`   | No       | `~/Downloads` | Directory to save the audio file                                          |
| `recording_id` | No       | —             | Check status of a previous download, or stop it when combined with `stop` |
| `stop`         | No       | `false`       | Stop a live recording. Requires `recording_id`.                           |

Pass `url` to start a download. Pass `recording_id` to check status. Pass `recording_id` + `stop: true` to stop.

***

## Pipeline

Once a Space is downloaded, pipe it through the rest of Augent:

1. `spaces(url=...)` to download the audio
2. `spaces(recording_id=...)` to poll until complete
3. `transcribe_audio(audio_path=...)` to get the full transcript
4. `search_audio`, `deep_search`, `chapters`, `highlights`, etc.

Or use `take_notes(url=...)` directly if you just want formatted notes from the Space.

***

## Setup

X/Twitter requires authentication to access Space audio. Any account works, including a burner. This is a one-time setup.

1. Log into [x.com](https://x.com) in any browser
2. Open DevTools (F12 or Cmd+Option+I), go to **Application** tab, then **Cookies**, then `https://x.com`
3. Copy the `auth_token` and `ct0` cookie values
4. Create `~/.augent/auth.json`:

```json theme={null}
{"auth_token": "PASTE_HERE", "ct0": "PASTE_HERE"}
```

Tokens are stored locally and only sent to Twitter's own servers to fetch audio. Augent never posts, DMs, follows, or modifies anything on your account. To revoke access, log out of Twitter or delete `~/.augent/auth.json`.

***

## Notes

<Tip>Live Spaces record from the current moment forward. Ended Spaces download the full recording.</Tip>

<Tip>Downloads run in the background. Your agent can continue doing other work while the Space downloads.</Tip>

<Tip>The `recording_id` is only valid for the current session. If the MCP server restarts, active recordings are lost.</Tip>

<Tip>Combine with `identify_speakers` to find out who said what in a multi-speaker Space.</Tip>