{"id":28228108,"url":"https://github.com/gradion-ai/freeact","last_synced_at":"2026-03-13T09:01:36.063Z","repository":{"id":270203380,"uuid":"899383871","full_name":"gradion-ai/freeact","owner":"gradion-ai","description":"Agent harness and CLI tool that acts and self-improves via code actions","archived":false,"fork":false,"pushed_at":"2026-03-09T10:28:31.000Z","size":53753,"stargazers_count":127,"open_issues_count":3,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-09T14:11:37.495Z","etag":null,"topics":["ai-agent","code-act","code-action","code-mode","ipybox","programmatic-tool-calling","sandbox-runtime"],"latest_commit_sha":null,"homepage":"https://gradion-ai.github.io/freeact/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gradion-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-12-06T06:43:51.000Z","updated_at":"2026-03-09T10:27:16.000Z","dependencies_parsed_at":"2025-01-14T14:26:03.811Z","dependency_job_id":"d7e1d2dd-4494-4c53-8440-fd6a43882bbb","html_url":"https://github.com/gradion-ai/freeact","commit_stats":null,"previous_names":["gradion-ai/freeact"],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/gradion-ai/freeact","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradion-ai%2Ffreeact","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradion-ai%2Ffreeact/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradion-ai%2Ffreeact/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradion-ai%2Ffreeact/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gradion-ai","download_url":"https://codeload.github.com/gradion-ai/freeact/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradion-ai%2Ffreeact/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30463557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T06:34:02.089Z","status":"ssl_error","status_checked_at":"2026-03-13T06:33:49.182Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","code-act","code-action","code-mode","ipybox","programmatic-tool-calling","sandbox-runtime"],"created_at":"2025-05-18T14:09:25.991Z","updated_at":"2026-03-13T09:01:36.055Z","avatar_url":"https://github.com/gradion-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"docs/images/banner.png\" alt=\"freeact\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"left\"\u003e\n    \u003ca href=\"https://gradion-ai.github.io/freeact/\"\u003e\u003cimg alt=\"Website\" src=\"https://img.shields.io/website?url=https%3A%2F%2Fgradion-ai.github.io%2Ffreeact%2F\u0026up_message=online\u0026down_message=offline\u0026label=docs\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/freeact/\"\u003e\u003cimg alt=\"PyPI - Version\" src=\"https://img.shields.io/pypi/v/freeact?color=blue\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/gradion-ai/freeact/releases\"\u003e\u003cimg alt=\"GitHub Release\" src=\"https://img.shields.io/github/v/release/gradion-ai/freeact\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/gradion-ai/freeact/actions\"\u003e\u003cimg alt=\"GitHub Actions Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/gradion-ai/freeact/test.yml\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/gradion-ai/freeact/blob/main/LICENSE\"\u003e\u003cimg alt=\"GitHub License\" src=\"https://img.shields.io/github/license/gradion-ai/freeact?color=blueviolet\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nFreeact is a lightweight agent harness and CLI tool that acts by executing code and shell commands in a stateful execution environment. It uses code actions to improve itself and its tool library.\n\nIt generates Python APIs for MCP servers and calls their tools programmatically (\"code mode\") instead of JSON. This enables tool composition in code actions in a single inference pass.\n\nFreeact has a tiny core and uses sandboxed IPython kernels to execute both Python code and shell commands in a uniform way. Execution runs locally with fine-grained approval of actions.\n\n\u003e [!NOTE]\n\u003e **Supported models**: Freeact supports any model compatible with [Pydantic AI](https://ai.pydantic.dev/), with `gemini-3-flash-preview` as the default. See [Models](https://gradion-ai.github.io/freeact/models/) for provider configuration and examples.\n\n## Documentation\n\n- 📚 [Documentation](https://gradion-ai.github.io/freeact/)\n- 🚀 [Quickstart](https://gradion-ai.github.io/freeact/quickstart/)\n- 🤖 [llms.txt](https://gradion-ai.github.io/freeact/llms.txt)\n- 🤖 [llms-full.txt](https://gradion-ai.github.io/freeact/llms-full.txt)\n\n## Capabilities\n\n| Capability | Description |\n|---|---|\n| **Code actions** | Freeact agents act via Python code and shell commands. This enables tool composition and intermediate result processing in a single LLM inference pass. |\n| **Local execution** | Freeact executes code and shell commands locally in an IPython kernel provided by [ipybox](https://github.com/gradion-ai/ipybox). Data, configuration and generated tools live in local workspaces. |\n| **Sandbox mode** | IPython kernels optionally run in a sandbox environment based on Anthropic's [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime). It enforces filesystem and network restrictions on OS-level. |\n| **MCP code mode** | Freeact calls MCP server tools programmatically\u003csup\u003e1)\u003c/sup\u003e via generated Python APIs. This enables composition of tool calls in code actions with much lower latency. |\n| **Tool discovery** | Tools are discovered via category browsing or hybrid BM25/vector search. On-demand loading frees the context window and scales to larger tool libraries. |\n| **Tool authoring** | Agents can create new tools, enhance existing tools, or save code actions as reusable tools. This captures successful experience as executable knowledge. |\n| **Agent skills** | Skills give agents new capabilities and expertise based on [agentskills.io](https://agentskills.io/). They compose naturally with code actions and agent-authored tools. |\n| **Subagent delegation** | Tasks can be delegated to subagents, each using their own sandbox. It enables specialization and parallelization without cluttering the main agent's context. |\n| **Action approval** | Fine-grained approval of code actions and (programmatic) tool calls from both main agents and subagents. Enables human control over potentially risky actions. |\n| **Session persistence** | Freeact persists agent state incrementally. Persisted sessions can be resumed and serve as a record for debugging, evaluation, and improvement. |\n\n## Usage\n\n| Component | Description |\n|---|---|\n| **[Agent SDK](https://gradion-ai.github.io/freeact/sdk/)** | Agent harness and Python API for building freeact applications. |\n| **[CLI tool](https://gradion-ai.github.io/freeact/cli/)** | Terminal interface for interactive conversations with a freeact agent. |\n\n---\n\n\u003csup\u003e1)\u003c/sup\u003e Freeact also supports MCP server integration via JSON tool calling, but the recommended approach is programmatic tool calling.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgradion-ai%2Ffreeact","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgradion-ai%2Ffreeact","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgradion-ai%2Ffreeact/lists"}