THE CHELUS GUIDE

Useful tools. An explicit say-so.

Chelus can work with files, web pages, and shell commands. Risky actions ask for approval by default.

What the agent can use

Tool	What it does
`list_dir`, `read_file`	Inspect permitted files; page through longer output.
`search_files`	Find file names or text by regex, with ripgrep when installed.
`write_file`, `edit_file`	Write a file or replace a specific piece of text, with approval.
`run_shell`	Run a shell command, with approval.
`shell_jobs`	List background commands, read logs, or stop a run.
`web_fetch`, `web_search`	Read public pages or search the web. Owner only.
`notes_search`, `note_read`, `note_write`, `note_edit`, `note_move`, `note_trash`	Search and keep the notes folder. Owner only, no approval; nothing is erased.
`battery_status`	Read battery information when Termux:API is installed.

You describe the task; the model selects tools. Availability still depends on your device, configuration, and optional packages.

Choose the approval scope

Allow once: approve that call only.
Allow for this conversation: cover ordinary risky tools in this conversation, including later turns and after a restart. /new asks again.
Always this action: remember the exact tool, normalized working directory, target, and effect arguments. A different command or content asks again.

“Always” is not a command-prefix or execute-everything grant. Denied, unanswered, and allow-once requests save no grant. Skill approvals are separate. Telegram requests time out after three minutes.

chelus approvals
chelus approvals revoke ID
chelus approvals clear

Use /approvals in Telegram. Listings show grant IDs and scope without revealing stored commands or file contents.

Shell access is not a sandbox

Approve commands with the device in mind.

Approved shell commands run with Termux’s permissions. The file-tool protections are not a shell sandbox. The one-shot chelus ask command refuses risky tools unless you explicitly pass --allow-risky, and does not reuse saved ordinary grants.

File tools protect Chelus’s configuration and data directories and ~/.ssh. Guests are additionally confined to workdir and cannot run risky tools.

Let slower commands finish

The foreground shell limit defaults to 120 seconds. Slower commands can run in the background for up to 30 minutes, with bounded logs and a finish notice from the Telegram bridge. At most three run at once. Jobs can survive a bridge restart, but not a reboot.

Long tool output is trimmed for context and saved temporarily for read_file to page through. Saved shell output masks credential-looking strings; do not rely on masking to make a secret safe to print.

Web access

Owner-only web tools need no approval. Fetching is restricted to public HTTP(S) text pages: no local networks, cloud metadata addresses, cookies, or credentials. Search uses DuckDuckGo’s HTML page, or Brave Search when a key is configured. Rate limits can prevent results.

The verification notes record which paths have been exercised live.

Found a gap? Open an issue or consult the source documentation.