# freeact

> Freeact code action agent

General-purpose AI agent that acts via code actions through a unified execution interface.

Freeact is a lightweight, general-purpose agent that acts via code actions in a stateful execution environment provided by ipybox.
A unified execution interface allows code actions to contain any combination of Python code, shell commands, and programmatic MCP tool calls, generated in one LLM inference pass.

For programmatic MCP tool calling ("code mode"), freeact generates typed Python APIs from MCP server schemas.
The agent inspects generated APIs prior to execution and composes them within code actions based on available type information.
Successful code actions can be saved as reusable tools, capturing agent experience as executable knowledge, optionally combined with agent skills.

Freeact supports tool discovery via agentic and semantic search, loading only task-relevant tool information into the context window.
It can enforce application-level approval of code actions, shell commands, and programmatic tool calls, originating from both main agents and subagents.
Freeact runs locally on your computer and is available as a CLI tool and Python SDK.


## Getting started

- [Overview](https://gradion-ai.github.io/freeact/index.md): Overview, usage, and capabilities
- [Installation](https://gradion-ai.github.io/freeact/getting-started/installation/index.md): Setup and installation instructions
- [CLI quickstart](https://gradion-ai.github.io/freeact/getting-started/quickstart/index.md): Running a first task with the CLI tool
- [First agent with the SDK](https://gradion-ai.github.io/freeact/getting-started/sdk-tutorial/index.md): Building a first agent with the Agent SDK

## How-to guides

- [Configure models](https://gradion-ai.github.io/freeact/guides/models/index.md): Model configuration, provider settings, and custom providers
- [Add custom tool servers](https://gradion-ai.github.io/freeact/guides/tool-servers/index.md): Bundled tool servers and custom MCP servers for JSON and programmatic tool calling
- [Configure tool discovery](https://gradion-ai.github.io/freeact/guides/tool-discovery/index.md): Basic and hybrid tool discovery setup
- [Manage permissions](https://gradion-ai.github.io/freeact/guides/permissions/index.md): Approval prompts, permission rules, and approval automation
- [Use sandbox mode](https://gradion-ai.github.io/freeact/guides/sandbox/index.md): Sandbox mode for code execution and MCP servers
- [Persist and resume sessions](https://gradion-ai.github.io/freeact/guides/sessions/index.md): Session persistence and resumption
- [Create agent skills](https://gradion-ai.github.io/freeact/guides/skills/index.md): Custom and bundled agent skills
- [Save code actions as tools](https://gradion-ai.github.io/freeact/guides/saving-tools/index.md): Saving code actions as reusable tools
- [Enhance generated tools](https://gradion-ai.github.io/freeact/guides/enhancing-tools/index.md): Enhancing generated tool APIs with output parsers
- [Use Python packages](https://gradion-ai.github.io/freeact/guides/python-packages/index.md): Using Python packages in code actions

## Reference

- [Configuration](https://gradion-ai.github.io/freeact/reference/configuration/index.md): Configuration file format, agent and terminal settings, and directory structure
- [CLI](https://gradion-ai.github.io/freeact/reference/cli/index.md): CLI commands, options, and interactive mode
- [Environment variables](https://gradion-ai.github.io/freeact/reference/environment/index.md): API keys, variable references, and hybrid search variables
- [Permission rules](https://gradion-ai.github.io/freeact/reference/permission-rules/index.md): Permission rule format, tiers, and pattern matching semantics

## Concepts

- [Code actions](https://gradion-ai.github.io/freeact/concepts/code-actions/index.md): Code actions and unified execution of Python code, shell commands, and tool calls
- [Approvals and permissions](https://gradion-ai.github.io/freeact/concepts/approvals/index.md): Approval model and permission tiers
- [Runtime model](https://gradion-ai.github.io/freeact/concepts/runtime/index.md): Event stream, turns, subagents, and cancellation

## API Reference

- [Agent](https://gradion-ai.github.io/freeact/api/agent/index.md): Agent class, events, and approval workflow
- [Config](https://gradion-ai.github.io/freeact/api/config/index.md): Configuration loading and resolution
- [Generate](https://gradion-ai.github.io/freeact/api/generate/index.md): MCP tool API generation
- [Permissions](https://gradion-ai.github.io/freeact/api/permissions/index.md): Permission management for tool approvals