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

# Ask

> Send a message from one agent session to another and get the response back

`clideck ask` lets one agent session send a question to another active session and wait for the answer. The response prints to stdout so the caller can use it immediately.

This is designed for agent-to-agent communication — one LLM agent asks another for help without you in the loop.

## Discovery

Before asking, discover who's available:

```bash theme={null}
clideck agents
```

This lists active sessions in the same project as the caller. Output looks like:

```
Programmer (self, claude-code, idle) id=abc123
Reviewer (peer, claude-code, idle) id=def456
```

To see sessions across all projects (with their cross-project addresses):

```bash theme={null}
clideck agents --all
```

Add `--json` for machine-readable output.

## Same-Project Ask

When the caller and target are in the same project, use the session name directly:

```bash theme={null}
clideck ask --session "Reviewer" --message "Review my changes and return only findings."
```

Or with positional arguments:

```bash theme={null}
clideck ask Reviewer "Review my changes and return only findings."
```

The target is resolved within the caller's project only. If no match is found in the same project, the request fails — it does not search other projects.

## Cross-Project Ask

To reach a session in a different project, use the `@project/session` format:

```bash theme={null}
clideck ask "@website/Docs Writer" "Check if the docs mention the new CLI flags." --timeout 15m
```

The project name and session name are both resolved case-insensitively. If multiple projects or sessions share a name, use the ID instead.

## Quoting Targets with Spaces

If the session name or project name contains spaces, quote the entire target:

```bash theme={null}
clideck ask "research manager" "Check this plan."
clideck ask "@My Project/Docs Writer" "Update the changelog."
```

When using `--session`, the quotes go around the value:

```bash theme={null}
clideck ask --session "research manager" --message "Check this plan."
```

## Piping Input

You can pipe a file or command output as the message via stdin:

```bash theme={null}
cat notes.md | clideck ask --session "Docs Writer" --timeout 10m
```

When stdin is piped, the `--message` flag is not needed.

## Busy Target Behavior

`clideck ask` only sends to **idle** sessions. If the target is currently working, the request fails immediately with:

```
Target session "Reviewer" is busy. CliDeck ask only sends to idle sessions.
Try again later, choose another idle session, or ask the user how to proceed.
```

This is intentional — injecting a message into a working agent would interrupt its current task. Wait for the target to finish, or pick a different session.

## Timeout

The target is another LLM agent. It may need minutes to read files, think, use tools, and compose an answer.

```bash theme={null}
clideck ask --session "Programmer" --message "Refactor the auth module" --timeout 15m
```

| Flag               | Default    | Max    |
| ------------------ | ---------- | ------ |
| `--timeout` / `-t` | 10 minutes | 1 hour |

Accepts durations like `30s`, `10m`, `1h`.

<Warning>
  **Set both timeouts.** `clideck ask --timeout` controls how long the ask command waits. But if your caller agent's shell or tool-call timeout is shorter, the shell kills the process first — the target agent may keep working but the caller loses the response. Make sure both timeouts are high enough.
</Warning>

While waiting, `clideck ask` prints progress updates to stderr every 15 seconds showing the target's status and elapsed time. Use `--no-progress` to suppress these.

## How It Works

1. The caller agent runs `clideck ask` from its terminal
2. CliDeck resolves the target session (same-project or cross-project)
3. If the target is busy, the request fails immediately
4. CliDeck injects the message into the target's terminal as a bracketed paste, prefixed with `[CliDeck ask from <caller>]`
5. CliDeck waits for the target agent to go from working back to idle
6. The target's response is captured from the transcript and printed to the caller's stdout

## Full CLI Reference

```
clideck ask --session <name-or-id> --message <text> [--timeout 10m]
clideck ask <name-or-id> <message> [--timeout 10m]
clideck ask "@project/session" <message> [--timeout 10m]
cat file.txt | clideck ask --session <name-or-id> [--timeout 10m]
```

| Option            | Description                                                             |
| ----------------- | ----------------------------------------------------------------------- |
| `-s`, `--session` | Target session name or ID                                               |
| `-m`, `--message` | Message to send (or use stdin)                                          |
| `-t`, `--timeout` | Wait time (e.g. `30s`, `10m`, `1h`). Default: `10m`                     |
| `--url`           | CliDeck server URL. Default: `CLIDECK_URL` or `http://127.0.0.1:<port>` |
| `--no-progress`   | Suppress progress updates on stderr                                     |

<Note>
  `clideck ask` requires `CLIDECK_SESSION_ID` to be set, which CliDeck sets automatically for sessions launched from the UI. It cannot be used from a terminal outside CliDeck.
</Note>