Cortex-Inara/cortex/static/TOOLS.md

Tool Reference

This reference covers all 45 orchestrator tools available when the ⚡ toggle is on. Tools are invoked automatically by the orchestrator — you don't call them directly.

¹ Admin only — requires the admin role. Invisible to regular users.
² Confirmation required — the orchestrator pauses and shows Confirm / Deny buttons before executing.

---

Web

Tool	What it does
web_search	DuckDuckGo search — returns titles, URLs, and snippets for the top results
http_fetch	Fetch a specific URL and return the response body (8 192 char cap)

Files ¹

Tool	What it does
file_read ¹	Read any file under the persona home directory
file_list ¹	List files and directories with sizes (200 entry cap)
file_write ¹ ²	Write or append to a file under the persona home directory

Shell ¹

Tool	What it does
shell_exec ¹ ²	Run any shell command on the Cortex host; timeout 1–120 s
claude_allow_dir ¹	Add a directory to Claude Code's auto-allowed paths

System ¹

Tool	What it does
cortex_restart ¹ ²	Restart the Cortex service (5 s delay); connection drops — refresh the page
cortex_logs ¹	Recent lines from the systemd journal (default 50, max 200)
cortex_status ¹	Current git branch, commit, ahead/behind remote, and service state
cortex_update ¹ ²	git pull + syntax check all .py files; reports what changed. Does not restart automatically — call cortex_restart after reviewing

Tasks

Tool	What it does
task_list	List personal tasks; pass include_done=true to include completed
task_create	Create a task with title, optional notes and due date
task_update	Update any fields on an existing task
task_complete	Mark a task as complete

Cron

Tool	What it does
cron_list	List all scheduled jobs for this persona
cron_add	Add a scheduled job — accepts cron syntax or plain-English interval
cron_remove ²	Remove a scheduled job by ID
cron_toggle	Enable or disable a job without removing it

Reminders

Tool	What it does
reminders_add	Add a reminder with optional label; surfaced in context at Tier 2+
reminders_list	List all pending reminders, numbered for easy removal
reminders_remove	Remove a single reminder by number (call reminders_list first)
reminders_clear ²	Clear all reminders at once

Scratchpad

Tool	What it does
scratch_read	Read the current scratchpad
scratch_write	Overwrite the scratchpad with new content
scratch_append	Append a timestamped section to the scratchpad
scratch_clear	Erase the scratchpad

Notifications ¹

Tool	What it does
web_push	Send a browser push notification to the active user's registered devices
email_send ¹	Send an email via SMTP; recipient must match your email_allowlist.json
nc_talk_send ¹	Send a message to a Nextcloud Talk conversation

Aether Journals

Tool	What it does
ae_journal_list	List all journals for the configured AE account (returns names + IDs)
ae_journal_search	Search entries by keyword, tag, date range, type, status, or priority
ae_journal_entries_list	Browse all entries in a specific journal, newest first; paginated
ae_journal_entry_read	Read the full content of a single entry by ID
ae_journal_entry_create	Create a new entry with title, content, tags, and summary
ae_journal_entry_update	Patch any fields on an existing entry (title, content, tags, summary, enable)
ae_journal_entry_disable	Soft-delete an entry (enable=false) without permanently removing it
ae_journal_entry_append	Append a timestamped section to the bottom of an entry's content
ae_journal_entry_prepend	Prepend a timestamped section to the top of an entry's content

Aether Tasks ¹

Tool	What it does
ae_task_list ¹	List tasks from the agents_sync Kanban board

Agent Notes

Private, durable notes visible only to the orchestrator — not surfaced to users. Persist across sessions. Only available in orchestrated (tool-enabled) sessions.

Tool	What it does
agent_notes_read	Read the current private notes file
agent_notes_write	Overwrite the notes file completely
agent_notes_append	Append a timestamped entry (keeps last 3 backups automatically)
agent_notes_clear	Erase all notes (backs up first)

Agents ¹

Spawn sub-agents that run their own tool loop using a specific role's model and tools.

Tool	What it does
spawn_agent ¹	Spawn a sub-agent synchronously — blocks until the task completes or times out. Params: task, role (default chat), tier (1–4, default 1), timeout seconds, max_rounds override. Only works with local_openai and gemini_api models.