klax is a messenger bridge for coding agents. It connects Telegram, MAX, and VK chats to a local CLI backend and streams progress back into the chat.

Supported backends:

• claude via Claude Code CLI
• codex via OpenAI Codex CLI

The daemon keeps per-chat sessions, resumes them across restarts, runs the agent in the session working directory, and sends intermediate tool activity while the answer is being built.

Messenger -> klax daemon -> agent CLI -> Messenger

At a high level:

1. klax polls enabled messengers.
2. It maps the incoming chat to a stored session.
3. It starts or resumes the selected backend in that session's working directory.
4. It streams tool activity and the final result back to the messenger.

• Telegram, MAX, and VK transports
• claude and codex backends
• Persistent sessions with resume support
• Per-session backend, model, thinking level, and sandbox mode
• Group mode with a dedicated working directory per group chat
• systemd user service management
• Release update flow, plus local-source rebuilds via source_dir

• Linux (amd64 or arm64)
• systemd --user
• At least one configured backend:

Install and authenticate Claude Code CLI:

curl -fsSL https://claude.ai/install.sh | bash

Install Codex CLI:

npm install -g @openai/codex

Codex must be authenticated before use (e.g. via OPENAI_API_KEY or codex auth).

curl -fsSL https://raw.githubusercontent.com/PiDmitrius/klax/main/install.sh | bash

The installer places the binary in ~/.local/bin/klax, checks PATH wiring, and prepares the user environment for systemd --user.

klax setup
klax install
klax start

klax setup creates or updates ~/.config/klax/config.json interactively. Press Enter to keep the current value, or enter - to clear it.

Main config file:

• ~/.config/klax/config.json

Minimal example:

{
  "tg_token": "123456:AAH...",
  "tg_allowed_users": [123456789],
  "default_cwd": "/home/user/work",
  "default_backend": "claude",
  "backends": {
    "claude": {},
    "codex": {}
  },
  "source_dir": ""
}

Common fields:

Runtime backend settings such as backend selection, model, thinking level, and sandbox mode are configured per session from chat via /settings.

Primary commands available in messenger chats:

Anything that is not recognized as a control command is forwarded to the active backend.

klax setup       interactive first-time setup
klax install     install systemd user service
klax uninstall   remove systemd user service
klax start       start the service (--foreground to run directly)
klax stop        stop the service
klax restart     restart the service
klax update      update from GitHub release or rebuild from source_dir
klax fallback    install latest GitHub release, ignoring source_dir
klax status      show service status
klax version     print version

Session state is stored in:

• ~/.local/share/klax/sessions.json

Config is stored in:

• ~/.config/klax/config.json

Each session stores:

• backend session ID (claude session UUID or codex thread ID)
• session name
• working directory
• selected backend
• model, thinking, and sandbox overrides
• counters and context metadata

Direct-message sessions are keyed by user identity. With users mapping configured, one person can share the same DM sessions across transports.

klax update behaves in one of two ways:

• If source_dir is empty, it downloads the latest GitHub release and installs it.
• If source_dir is set, it rebuilds from local source and installs that binary instead.

The daemon watches for the restart marker, finishes the current task, notifies chats, exits, and relies on systemd --user to come back up.

klax install writes a user service based on klax.service:

• ExecStart=%h/.local/bin/klax start --foreground
• Restart=always
• RestartSec=5
• StartLimitBurst=3
• StartLimitIntervalSec=60

If klax crashes 3 times within 60 seconds, systemd stops restarting it. To investigate and recover:

klax status                            # see the error
journalctl --user -u klax --no-pager   # full logs
systemctl --user reset-failed klax     # clear the failure counter
klax start                             # try again

Common causes: invalid bot token, network unreachable at startup, broken config. Check ~/.config/klax/config.json and re-run klax setup if needed.

cmd/klax/           daemon, CLI entrypoints, chat command handling
internal/config/    config load/save and normalization
internal/session/   session store and scope defaults
internal/runner/    backend adapters, streaming parser, tool formatting
internal/tg/        Telegram transport
internal/max/       MAX transport
internal/vk/        VK transport