# 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.


## Documentation

- [Overview](https://gradion-ai.github.io/freeact/index.md): Overview, usage, and capabilities
- [Installation](https://gradion-ai.github.io/freeact/installation/index.md): Setup and installation instructions
- [Quickstart](https://gradion-ai.github.io/freeact/quickstart/index.md): Getting started with code actions and MCP tools
- [Configuration](https://gradion-ai.github.io/freeact/configuration/index.md): Configuration directory structure and MCP server setup
- [Code Execution](https://gradion-ai.github.io/freeact/execution/index.md): Code and shell command execution in IPython kernels
- [Sandbox Mode](https://gradion-ai.github.io/freeact/sandbox/index.md): Sandbox mode for code execution and MCP servers
- [Models](https://gradion-ai.github.io/freeact/models/index.md): Model configuration, provider settings, and custom providers
- [Agent SDK](https://gradion-ai.github.io/freeact/sdk/index.md): Agent SDK for agent integration
- [CLI Tool](https://gradion-ai.github.io/freeact/cli/index.md): CLI tool and interactive mode

## 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 initialization and loading
- [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