CLI tool

The freeact or freeact run command starts the interactive mode:

freeact

A .freeact/ configuration directory is created automatically if it does not exist yet. The init subcommand initializes the configuration directory without starting the interactive mode:

freeact init

Options

Option	Description
--sandbox	Run code execution in sandbox mode.
--sandbox-config PATH	Path to sandbox configuration file.
--session-id UUID	Resume a previous session by its UUID.
--skip-permissions	Run tools without prompting for approval.
--log-level LEVEL	Set logging level: debug, info (default), warning, error, critical.

Examples

Running code execution in sandbox mode:

freeact --sandbox

Running with a custom sandbox configuration:

freeact --sandbox --sandbox-config sandbox-config.json

Resuming a previous session:

freeact --session-id 550e8400-e29b-41d4-a716-446655440000

If enable_persistence is false in .freeact/agent.json, passing --session-id exits with an error.

Interactive Mode

The interactive mode provides a conversation interface with the agent in a terminal window.

User messages

Key	Action
Enter	Send message
Ctrl+J	Insert newline
Option+Enter (macOS) Alt+Enter (Linux/Windows)	Insert newline (Ctrl+J fallback)
Escape	Cancel the current agent turn, or clear input when idle
Ctrl+Q	Quit

Clipboard

Clipboard behavior depends on terminal key forwarding.

• Paste into the prompt input: Cmd+V or Ctrl+V.
• Copy selected text from Freeact widgets: Cmd+C may not work in some terminals. Use Ctrl+C instead.
• Additional terminal fallbacks: Ctrl+Shift+C / Ctrl+Insert for copy, Ctrl+Shift+V / Shift+Insert for paste.

Expand and Collapse

Use Ctrl+O to toggle all collapsible boxes between expanded and configured state.

The shortcut is configured in .freeact/terminal.json under expand_all_toggle_key.

File References

Include file paths directly in the prompt. The model uses built-in filesystem tools to read them when needed.

screenshot.png What does this show?
Transcribe this voice-note.wav
images/ Describe these images

Type @ in the prompt to open a file picker for easier path insertion. The @ prefix is stripped before sending, so @screenshot.png and screenshot.png are equivalent.

Skill Invocation

The agent automatically uses skills when a request matches a skill's description. The /skill-name syntax is a shortcut to invoke a specific skill explicitly:

/plan my project requirements
/commit fix login bug

• Type / at the start of a prompt to open a skill picker.
• Select a skill to insert its name, then type arguments after it.
• Text after the skill name is passed as arguments to the skill.
• Skill locations: .agents/skills/ (project) and .freeact/skills/ (bundled).

Cancellation

Press Escape during an active agent turn to cancel it. This interrupts the current operation (LLM streaming, code execution, or approval wait), stops the turn, and re-enables the prompt input.

Approval Prompt

Before executing code actions, shell commands, and tool calls, the agent requests approval. Shell commands and programmatic tool calls within code actions are intercepted during execution and approved individually. For shell commands the prompt displays the verbatim command being executed; for other action types it displays a suggested permission pattern that summarizes the action:

Approve? [Y/n/a/s] git add src/main.py

Key	Action
y / Enter	Approve this invocation only
n	Reject (ends the current agent turn)
a	Edit pattern, then save as always-allow rule
s	Edit pattern, then save as session-allow rule

Pressing a or s opens an editable input pre-filled with the suggested permission pattern (not the verbatim text shown above). Edit the pattern to broaden or narrow the rule (e.g. change filesystem_read_file src/main.py to filesystem_* src/**), then press Enter to save the rule and approve. While editing, approval hotkeys are disabled so you can type freely.

Always-allow rules persist to .freeact/permissions.json across sessions. Session-allow rules are in-memory and cleared when the session ends. Future actions matching a saved rule are auto-approved without prompting.

What the bar displays depends on the action type:

Action	Bar shows	Suggested pattern (when pressing a/s)
Shell command (!cmd and split sub-commands)	Verbatim command, e.g. git add src/main.py	cmd subcmd * heuristic, e.g. git add *
Shell magic (%%bash)	First non-empty line + (+N more lines) summary; full script is shown in the Shell Script box above the bar	Full script with newlines escaped as \n
Code action	Tool name, e.g. ipybox_execute_ipython_cell	Same
File read/write/edit	Tool name + path, e.g. filesystem_write_text_file src/main.py	Same
Other tool calls	Tool name, e.g. github_search_repositories	Same

See Permissions for the persisted format and pattern syntax.

Automatic approval

Use the --skip-permissions CLI option to run the agent with full action auto-approval.