> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# Channel sessions and sub-agent delegation

> Per-channel session continuity for webhooks and CLI, silence tokens, and isolated background sub-agents.

Arka provides **channel sessions** and **sub-agent delegation** — patterns inspired by [Hermes Agent](https://github.com/NousResearch/hermes-agent), not a separate product integration. They add per-channel conversation continuity, webhook session handoff, and isolated background sub-agents.

## Features

| Concept                   | Arka feature                                                               |
| ------------------------- | -------------------------------------------------------------------------- |
| Per-chat session store    | `arka session` — keyed by `channel:chat_id`                                |
| Cross-platform continuity | Webhook + `arka ask` share the same session when `channel`/`chat_id` match |
| Silence tokens            | `[SILENT]`, `NO_REPLY` suppress webhook outbound delivery                  |
| Sub-agent delegation      | `subagent spawn` — isolated background agent tasks                         |

Arka does **not** ship full gateway adapters (Telegram, Discord, etc.). Use [webhook ingress](/guides/openclaw-features) and channel bridges, then attach channel sessions on top.

## Message sessions

Per-channel conversation turns stored under `~/.config/arka/message-sessions/`:

```bash theme={null}
arka session push cli default user "Start the deploy checklist"
arka session push cli default assistant "Step 1: run tests"
arka session context cli default
arka session resume cli default
arka session list
arka session reset telegram 123456789
arka session status
```

Sessions are keyed as `channel:chat_id` (e.g. `webhook:slack`, `cli:default`, `telegram:987654321`).

### CLI continuity

When `MESSAGE_SESSIONS=1` (default), `arka ask` and the chat engine automatically read and write the `cli:default` session (override with `MESSAGE_SESSION_CHANNEL` and `MESSAGE_SESSION_CHAT_ID`). Start a thread in the terminal, continue via webhook with the same channel and chat ID, or vice versa.

### Webhook continuity

When `WEBHOOK_ENABLED=1`, inbound POST bodies can include:

```json theme={null}
{
  "text": "What's the deploy status?",
  "channel": "telegram",
  "chat_id": "123456789"
}
```

Arka appends the user turn, injects prior session context into the agent prompt, stores the assistant reply, and returns `chat_id` in the response.

### Silence tokens

Explicit silence tokens let group chats and automations store a turn without sending outbound text:

* `[SILENT]`
* `SILENT`
* `NO_REPLY`
* `NO REPLY`

When the agent's final response is exactly one of these (case-insensitive), the webhook returns `"silent": true` and an empty `output` field. The turn is still stored in the session transcript.

External MCP clients can check the same tokens with `arka_sessions` action `silence_check` (returns `{ "silent": true|false, "tokens": [...] }`).

### Environment variables

| Variable                       | Default                           | Purpose                                     |
| ------------------------------ | --------------------------------- | ------------------------------------------- |
| `MESSAGE_SESSIONS`             | `1`                               | Enable (`0` to disable)                     |
| `MESSAGE_SESSIONS_DIR`         | `~/.config/arka/message-sessions` | Storage root                                |
| `MESSAGE_SESSION_IDLE_MINUTES` | `0`                               | Auto-reset after idle minutes (`0` = never) |
| `MESSAGE_SESSION_MAX_TURNS`    | `40`                              | Max turns kept per session                  |
| `MESSAGE_SESSION_CHANNEL`      | `cli`                             | Default channel for CLI chat                |
| `MESSAGE_SESSION_CHAT_ID`      | `default`                         | Default chat ID for CLI chat                |

Legacy `HERMES_SESSIONS*` variables remain supported as aliases.

Inbound turns are sanitized — injection patterns and unsafe content are blocked before storage.

## Sub-agent delegation

Spawn isolated background agents for parallel workstreams:

```bash theme={null}
subagent spawn "Summarize today's git log"
subagent list
subagent resume abc123def4
subagent status
```

Each sub-agent runs via the Python chat engine (with fish `agent` fallback). Task records live under `~/.cache/fish-agent/subagents/`.

### Security gates

| Gate                  | Blocks when                                   |
| --------------------- | --------------------------------------------- |
| `SUBAGENT_SECURITY=1` | Task fails `SECURITY_LLM` prompt verification |
| `SUBAGENT_MAX`        | Concurrent running agents exceed limit        |
| `SUBAGENT_MAX_CHARS`  | Task text too long                            |

Set `SUBAGENT_SYNC=1` to run synchronously (used in tests).

### Environment variables

| Variable            | Default                         | Purpose                             |
| ------------------- | ------------------------------- | ----------------------------------- |
| `SUBAGENT_ENABLED`  | `1`                             | Enable (`0` to disable)             |
| `SUBAGENT_DIR`      | `~/.cache/fish-agent/subagents` | Storage root                        |
| `SUBAGENT_MAX`      | `3`                             | Max concurrent background agents    |
| `SUBAGENT_TIMEOUT`  | `600`                           | Per-agent timeout (seconds)         |
| `SUBAGENT_SECURITY` | `1`                             | Apply security gates to spawn tasks |

Legacy `HERMES_SUBAGENT*` variables remain supported as aliases.

Sub-agents can attach to a message session via `--session-channel` and `--session-chat-id`.

## Background process status

Use `arka background processes` when you want one place to see what Arka currently has active:

```bash theme={null}
arka background processes
arka background processes --json
```

The report includes active sub-agent tasks, enabled routines, webhook status, configured MCP servers, and live OS processes that look Arka-owned such as `arka mcp serve`. The legacy command `arka background agent tasks` still works as an alias.

This command is read-only. It does not stop or restart agents, routines, or servers.

## Skill manifest gates

Plugin gates use `metadata.openclaw`, `metadata.arka`, or `metadata.hermes` — all merged the same way. See [OpenClaw-inspired gates](/guides/openclaw-features) for details.

## Heartbeat integration

`heartbeat status` reports channel session and sub-agent counts:

```bash theme={null}
heartbeat status
```

## Related features

* [Context layers](/guides/memory#context-layers) — how memory, session notes, and channel turns fit together
* [Session memory](/guides/openclaw-features) — long-term markdown notes (`MEMORY.md`)
* [Webhooks](/guides/openclaw-features) — verified external ingress
* [Security](/concepts/security) — global `SECURITY`, `SECURITY_LLM`, and `SECURITY_ACTIONS` flags


## Related topics

- [MCP integration for Cursor and Claude](/guides/mcp.md)
- [Agent Hub](/guides/agent-hub.md)
- [Sessions](/guides/sessions.md)
- [Long-term memory with Supermemory sync](/guides/memory.md)
- [Sakana Fugu orchestrator](/guides/fugu.md)