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

# Background investigations

> Run investigations asynchronously in the interactive shell and receive RCA completion notifications.

OpenSRE's interactive shell supports a **session-local background mode** for
investigations.

When background mode is enabled:

* new investigations run asynchronously
* the shell stays free for more questions and follow-ups
* completed RCAs are tracked in-session
* completion notifications can be sent to email (via the [`smtp`](/docs/smtp) integration), Telegram (via the [`telegram`](/docs/messaging/telegram) integration), Rocket.Chat (via the [`rocketchat`](/docs/messaging/rocketchat) integration), or any combination

<Note>
  This first version is **session-local only**. If the REPL process exits,
  in-flight background jobs stop with it.
</Note>

***

## Commands

| Command                                         | What it does                                                                                  |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `/background on`                                | Enable async investigation launches                                                           |
| `/background off`                               | Return to normal foreground execution                                                         |
| `/background status`                            | Show background mode, tracked job count, and active notify channels                           |
| `/background list`                              | List tracked jobs                                                                             |
| `/background show <task_id>`                    | Show the RCA summary and the per-channel notification result for one job                      |
| `/background use <task_id>`                     | Promote a completed job into the active follow-up context                                     |
| `/background notify list`                       | Show the channels a completed RCA is delivered to (default: **none**)                         |
| `/background notify set <channel[,channel...]>` | Set completion channels — `email`, `telegram`, `rocketchat`, or a comma-separated combination |

***

## Typical flow

1. Start the interactive shell.
2. Enable background mode:

```text theme={null}
/background on
```

3. Choose where the completed RCA is delivered. **Channels are empty by default — skip this and no
   notification is sent:**

```text theme={null}
/background notify set telegram    # or: email, rocketchat, or email,telegram
/background notify list           # confirm
```

4. Start an investigation:

```text theme={null}
/investigate datadog
```

or paste a fresh alert in free text.

5. Keep using the shell while the RCA runs.
6. When it completes:
   * inspect it with `/background show <task_id>`
   * adopt it into active follow-up context with `/background use <task_id>`

***

## RCA summary contents

Completed background jobs store:

* root cause
* top analysis items
* recommended next steps
* internal stats:
  * tool call count
  * investigation loop count
  * validity score

***

## Completion notifications

Notifications are **off by default** — pick your channels with `/background notify set`.

| Channel      | Delivered through                                 | Set up with                             |
| ------------ | ------------------------------------------------- | --------------------------------------- |
| `email`      | [`smtp`](/docs/smtp) integration                       | `opensre integrations setup smtp`       |
| `telegram`   | [`telegram`](/docs/messaging/telegram) integration     | `opensre integrations setup telegram`   |
| `rocketchat` | [`rocketchat`](/docs/messaging/rocketchat) integration | `opensre integrations setup rocketchat` |

All channels send the same summary — **Root cause**, **Top analysis**, **What to do next**, plus a
short internal stats section. Telegram and Rocket.Chat messages are plain text and are capped at the 4,096-character
limit.

Check what was actually delivered with `/background show <task_id>`: the `notify` row shows one
result per channel — `sent`, `failed: <error>`, or a setup hint such as
`missing telegram integration: TELEGRAM_BOT_TOKEN is not set.`

<Note>
  A notification problem never fails the investigation. If a channel is unconfigured
  or delivery errors, the RCA still completes, stays in `/background list`, and can still be promoted with
  `/background use`.
</Note>

***

## Current v1 limits

* interactive shell only — there is no `opensre background …` CLI command
* jobs are not persisted across REPL restarts
* completion does not automatically replace your active follow-up context
* you must run `/background use <task_id>` to promote a finished RCA