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

# 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.

Arka sanitizes inbound turns and blocks injection patterns and unsafe content before storage.

## Sub-agent delegation

Spawn isolated background agents for parallel workstreams:

```bash theme={null}
arka subagent spawn "Summarize today's git log"
arka subagent list
arka subagent resume abc123def4
arka 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 |
| `arka "SUBAGENT_MAX"` | Concurrent running agents exceed limit |
| `arka "SUBAGENT_MAX_CHARS"` | Task text too long |

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

### Environment variables

| Variable | Default | Purpose |
| - | - | - |
| `arka "SUBAGENT_ENABLED"` | `1` | Enable (`0` to disable) |
| `arka "SUBAGENT_DIR"` | `~/.cache/fish-agent/subagents` | Storage root |
| `arka "SUBAGENT_MAX"` | `3` | Max concurrent background agents |
| `arka "SUBAGENT_TIMEOUT"` | `600` | Per-agent timeout (seconds) |
| `arka "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`. Arka merges all three 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}
arka 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

- [Agent Hub](/guides/agent-hub.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)
- [AI agent guide — use Arka over MCP](/guides/ai-agents.md)
- [Sessions](/guides/sessions.md)
- [Testing Arka with the pytest suite](/guides/testing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.