freeai-code 0.1.3__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. freeai_code-0.2.0/PKG-INFO +331 -0
  2. freeai_code-0.2.0/README.md +298 -0
  3. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/__init__.py +1 -1
  4. freeai_code-0.2.0/free_code/agent.py +328 -0
  5. freeai_code-0.2.0/free_code/auth.py +181 -0
  6. freeai_code-0.2.0/free_code/builtin_manifest.py +166 -0
  7. freeai_code-0.2.0/free_code/cli.py +950 -0
  8. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/client.py +15 -2
  9. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/config.py +15 -2
  10. freeai_code-0.2.0/free_code/feedback_ui.py +84 -0
  11. freeai_code-0.2.0/free_code/manifest.py +223 -0
  12. freeai_code-0.2.0/free_code/mcp.py +366 -0
  13. freeai_code-0.2.0/free_code/models.py +162 -0
  14. freeai_code-0.2.0/free_code/remote_tools.py +416 -0
  15. freeai_code-0.2.0/free_code/sessions.py +111 -0
  16. freeai_code-0.2.0/free_code/telemetry.py +348 -0
  17. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/tools/__init__.py +32 -0
  18. freeai_code-0.2.0/free_code/tools/i18n.py +147 -0
  19. freeai_code-0.2.0/free_code/tools/web.py +60 -0
  20. freeai_code-0.2.0/free_code/toolset.py +100 -0
  21. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/ui/prompt.py +7 -1
  22. freeai_code-0.2.0/free_code/updater.py +157 -0
  23. freeai_code-0.2.0/freeai_code.egg-info/PKG-INFO +331 -0
  24. {freeai_code-0.1.3 → freeai_code-0.2.0}/freeai_code.egg-info/SOURCES.txt +22 -1
  25. {freeai_code-0.1.3 → freeai_code-0.2.0}/pyproject.toml +1 -1
  26. freeai_code-0.2.0/tests/test_agent.py +129 -0
  27. freeai_code-0.2.0/tests/test_cli.py +109 -0
  28. freeai_code-0.2.0/tests/test_login.py +67 -0
  29. freeai_code-0.2.0/tests/test_manifest.py +119 -0
  30. freeai_code-0.2.0/tests/test_mcp.py +71 -0
  31. freeai_code-0.2.0/tests/test_remote_tools.py +140 -0
  32. freeai_code-0.2.0/tests/test_telemetry.py +131 -0
  33. freeai_code-0.2.0/tests/test_tools_misc.py +106 -0
  34. freeai_code-0.2.0/tests/test_updater.py +76 -0
  35. freeai_code-0.2.0/tests/tests_helpers.py +5 -0
  36. freeai_code-0.1.3/PKG-INFO +0 -231
  37. freeai_code-0.1.3/README.md +0 -198
  38. freeai_code-0.1.3/free_code/agent.py +0 -262
  39. freeai_code-0.1.3/free_code/auth.py +0 -74
  40. freeai_code-0.1.3/free_code/cli.py +0 -447
  41. freeai_code-0.1.3/free_code/models.py +0 -53
  42. freeai_code-0.1.3/freeai_code.egg-info/PKG-INFO +0 -231
  43. {freeai_code-0.1.3 → freeai_code-0.2.0}/LICENSE +0 -0
  44. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/__main__.py +0 -0
  45. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/cloud.py +0 -0
  46. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/context/__init__.py +0 -0
  47. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/context/discovery.py +0 -0
  48. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/context/repo_map.py +0 -0
  49. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/context/window.py +0 -0
  50. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/streaming.py +0 -0
  51. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/tools/file_ops.py +0 -0
  52. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/tools/git_ops.py +0 -0
  53. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/tools/list_files.py +0 -0
  54. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/tools/search.py +0 -0
  55. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/tools/shell.py +0 -0
  56. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/tools/test_runner.py +0 -0
  57. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/ui/__init__.py +0 -0
  58. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/ui/diff_view.py +0 -0
  59. {freeai_code-0.1.3 → freeai_code-0.2.0}/free_code/ui/terminal.py +0 -0
  60. {freeai_code-0.1.3 → freeai_code-0.2.0}/freeai_code.egg-info/dependency_links.txt +0 -0
  61. {freeai_code-0.1.3 → freeai_code-0.2.0}/freeai_code.egg-info/entry_points.txt +0 -0
  62. {freeai_code-0.1.3 → freeai_code-0.2.0}/freeai_code.egg-info/requires.txt +0 -0
  63. {freeai_code-0.1.3 → freeai_code-0.2.0}/freeai_code.egg-info/top_level.txt +0 -0
  64. {freeai_code-0.1.3 → freeai_code-0.2.0}/setup.cfg +0 -0
@@ -0,0 +1,331 @@
1
+ Metadata-Version: 2.4
2
+ Name: freeai-code
3
+ Version: 0.2.0
4
+ Summary: Free AI coding assistant — open-source Claude Code alternative. pip install freeai-code
5
+ Author-email: "Free.ai" <hello@free.ai>
6
+ License: MIT
7
+ Project-URL: Homepage, https://free.ai/coder/
8
+ Project-URL: Documentation, https://free.ai/api/
9
+ Project-URL: Repository, https://github.com/muddyholdings/free-code
10
+ Project-URL: Bug Tracker, https://github.com/muddyholdings/free-code/issues
11
+ Project-URL: Changelog, https://free.ai/changelog/
12
+ Keywords: ai,coding,assistant,cli,free,claude-code,cursor,copilot
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.9
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Requires-Python: >=3.9
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: click>=8.0
27
+ Requires-Dist: rich>=13.0
28
+ Requires-Dist: httpx>=0.25
29
+ Requires-Dist: pyyaml>=6.0
30
+ Requires-Dist: pathspec>=0.11
31
+ Requires-Dist: tiktoken>=0.5
32
+ Dynamic: license-file
33
+
34
+ # Free.ai Coder
35
+
36
+ Free AI coding assistant for your terminal. A free, open-source alternative to Claude Code, Cursor, and GitHub Copilot.
37
+
38
+ **[Website](https://free.ai/coder/)** | **[PyPI](https://pypi.org/project/freeai-code/)** | **[npm](https://www.npmjs.com/package/freeai-code)** | **[Web IDE](https://free.ai/coder/)**
39
+
40
+ ## Install
41
+
42
+ One line, nothing to set up first (no Python, no pip, no sudo). It uses [uv](https://docs.astral.sh/uv/) and installs it for you if missing.
43
+
44
+ ```bash
45
+ # macOS / Linux
46
+ curl -fsSL https://free.ai/install.sh | sh
47
+ ```
48
+
49
+ ```powershell
50
+ # Windows (PowerShell)
51
+ irm https://free.ai/install.ps1 | iex
52
+ ```
53
+
54
+ Re-run the same line to upgrade. Pin a version with `FREE_CODE_VERSION=0.1.4` (PowerShell: `$env:FREE_CODE_VERSION = "0.1.4"`). The scripts are in [`install/`](install/): they use uv, else pipx, else a private venv in `~/.free-code`, and put `free-code` in `~/.local/bin`.
55
+
56
+ Already have Python or Node?
57
+
58
+ ```bash
59
+ pip install freeai-code
60
+ npm install -g freeai-code
61
+ ```
62
+
63
+ ## First run
64
+
65
+ Run `free-code` in a project. The free anonymous tier works with no account.
66
+
67
+ To sign in, run `free-code login`. It opens your browser at free.ai; sign in or create an account there, press Approve, and the CLI receives a key automatically (stored in `~/.free-code/config.yaml`, mode 600). On a remote machine it prints the address and a short code instead, so you can approve from any device (`free-code login --no-browser`). When the anonymous daily limit is used up, the CLI offers the same sign-in on the spot. Prefer to paste a key or use your own provider? `free-code login --manual`.
68
+
69
+ On first run in a terminal it also asks once whether to send anonymous crash and tool-failure reports. The default is no. See [Feedback](#feedback-opt-in).
70
+
71
+ ## Quick Start
72
+
73
+ ```bash
74
+ # Interactive coding session in your project directory
75
+ cd your-project/
76
+ free-code
77
+
78
+ # Ask a one-shot question about your codebase
79
+ free-code ask "How does the auth system work?"
80
+
81
+ # Execute a task
82
+ free-code run "Add unit tests for the User model"
83
+
84
+ # Run a task in the Free.ai cloud (codex-style) and watch it
85
+ free-code cloud "Fix the failing CI on main" --repo https://github.com/you/project
86
+
87
+ # Initialize and scan codebase
88
+ free-code init
89
+ ```
90
+
91
+ ## Commands
92
+
93
+ | Command | Description |
94
+ |---------|-------------|
95
+ | `free-code` | Interactive coding session (alias: `free-code chat`). `-c` resumes the latest session, `--resume ID` a specific one |
96
+ | `free-code -p "task"` | Non-interactive: print the answer and exit (see [Scripts and CI](#scripts-and-ci)) |
97
+ | `free-code ask "question"` | One-shot question about the codebase |
98
+ | `free-code run "task"` | Execute a coding task |
99
+ | `free-code models` | Every model Free.ai serves, free tier first (`--free`, `--paid`, `--type image`, a search word) |
100
+ | `free-code tools` | The tools the agent has (local, platform, MCP) and what needs approval (`--refresh` fetches the server manifest) |
101
+ | `free-code mcp add/list/remove/tools/trust` | Use MCP servers such as sttai-mcp |
102
+ | `free-code sessions` | Saved sessions you can resume |
103
+ | `free-code login` / `logout` | Sign in through the browser / forget the key |
104
+ | `free-code update` | Upgrade through whatever installed it (`--check`, `--version X`, `--dry-run`) |
105
+ | `free-code feedback "text"` | Send feedback you type |
106
+ | `free-code config feedback on\|off\|status` | Opt-in automatic reports |
107
+ | `free-code cloud "task"` | Run a coding task in the Free.ai cloud (`--repo URL`, `--model`, `--no-watch`, `--download DIR`) |
108
+ | `free-code tasks` | List your recent cloud tasks |
109
+ | `free-code init` | Initialize config, scan codebase |
110
+ | `free-code config` | Show current configuration |
111
+ | `free-code config set key value` | Set a config value |
112
+
113
+ Inside a session: `/model` (picker), `/models`, `/tools`, `/sessions`, `/resume`, `/feedback`, `/update`, `/compact`, `/clear`, `/diff`, `/status`, `/test`, `/files`, `/repo`, `/help`.
114
+
115
+ ## Features
116
+
117
+ - File read/write with diff preview and approval gates
118
+ - Shell command execution (with confirmation in safe mode)
119
+ - Git integration (status, diff, commit, log), test runner auto-detection (pytest, jest, go test, cargo test)
120
+ - `web_fetch` to read docs and issues
121
+ - Platform tools that call Free.ai with your key (see below): image, speech, music and video generation saved into your project, audio transcription, OCR of screenshots and PDFs, web search with citations, translation of strings and whole i18n files
122
+ - MCP client (stdio and HTTP): use sttai-mcp, Claude Desktop style servers and others
123
+ - Model picker over everything Free.ai serves, honest about free tier versus paid
124
+ - Sessions saved locally and resumable
125
+ - Non-interactive mode with JSON output and exit codes for scripts and CI
126
+ - Opt-in feedback, and self-update with a once-a-day version notice
127
+ - Tools shipped from a server manifest, so new tools and tool fixes arrive without a release (offline falls back to the built-in set)
128
+ - Streaming output, context window optimization, repo map, .gitignore-aware discovery
129
+ - Session sync with [web](https://free.ai/coder/) and cloud tasks on Free.ai's GPUs
130
+
131
+ ## Platform tools
132
+
133
+ The model can call these. They use your Free.ai key (or the free anonymous tier) and the public API at api.free.ai.
134
+
135
+ | Tool | What it does | Approval in safe mode |
136
+ |------|--------------|-----------------------|
137
+ | `generate_image` | Text to image, saved to a path in your project | yes (writes a file) |
138
+ | `generate_speech` | Text to speech audio, saved to your project | yes |
139
+ | `generate_music` | Short music clip, saved to your project | yes |
140
+ | `generate_video` | Short video clip, saved to your project (slow) | yes |
141
+ | `transcribe_audio` | Speech to text for an audio or video file | yes (uploads the file) |
142
+ | `ocr_image` | Text out of an image or PDF | yes (uploads the file) |
143
+ | `web_search` | Cited web answer plus source links | no |
144
+ | `translate_text` | Translate a short string | no |
145
+ | `translate_file` | Translate a JSON or YAML locale file, protecting `{0}`, `{name}`, `%s` placeholders; a string whose placeholders change is left in the source language and reported | writes the new file |
146
+
147
+ Free tier versus paid: `free-code models` marks each model. "free tier" means no token price (Free.ai's self-hosted models, within the daily limits); "paid" means billed in tokens and it needs a key with balance. Self-hosted image, video and audio models list no per-token price and count against the daily free allowance.
148
+
149
+ ## MCP servers
150
+
151
+ ```bash
152
+ pip install sttai-mcp
153
+ free-code mcp add stt-ai sttai-mcp --env STT_API_KEY='${STT_API_KEY}'
154
+ free-code mcp tools stt-ai # check it connects
155
+ free-code # its tools appear as mcp__stt_ai__<tool>
156
+ ```
157
+
158
+ `${NAME}` in `--env` values is read from your own environment, so no secret is written to disk. Servers live in `~/.free-code/mcp.json` (same `mcpServers` shape as Claude Desktop; `--url https://...` adds an HTTP server). A project can ship `.free-code/mcp.json`, but opening a repository must not start programs, so it is ignored until you run `free-code mcp trust` and it re-prompts if the file changes. MCP tools ask for approval in safe mode.
159
+
160
+ ## Scripts and CI
161
+
162
+ ```bash
163
+ free-code -p "summarize the failing tests" --yes # plain answer on stdout
164
+ free-code run "bump the version" --json --yes # one JSON object
165
+ free-code -p "review this diff: $(git diff)" # prompt built by your shell
166
+ ```
167
+
168
+ `--json` prints `{"ok", "response", "error", "tools": [{"tool","ok"}], "model", "session", "needs_approval"}`. Exit codes: 0 done, 1 failed (API or agent error), 3 an edit or command needed approval and none was given, 130 interrupted. Without a terminal nothing is ever approved implicitly: pass `--yes` to allow edits. `--yes` still refuses commands that match the dangerous list (`rm -rf`, `git reset --hard`, ...). `--max-steps`, `--model` and `--no-mcp` are available everywhere.
169
+
170
+ ## Feedback (opt-in)
171
+
172
+ Off until you say yes. First run in a terminal asks once (Enter means no). Change it any time:
173
+
174
+ ```bash
175
+ free-code config feedback on|off|status
176
+ ```
177
+
178
+ `FREE_CODE_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` force it off. `FREE_CODE_TELEMETRY_DRYRUN=1` prints every payload to stderr instead of sending it.
179
+
180
+ When on, exactly these can be sent to `https://free.ai/api/v1/code/telemetry/`, anonymously (no account, and the server stores no IP):
181
+
182
+ | Event | Contents |
183
+ |-------|----------|
184
+ | Crash | free-code version, OS name, Python version, install method, the exception class, free-code's own stack frames (file, line, function), and the exception message with quoted text, paths, numbers and long tokens replaced by placeholders |
185
+ | Tool failure | tool name, an error class (`not_found`, `timeout`, `rate_limited`...), model id, and the shape of the arguments: names and a type or size bucket such as `str:1-80`, never values. MCP tool names are not sent |
186
+ | Rating | thumbs up or down after a task (asked after the first task, then every fifth), plus a comment only if you type one |
187
+ | `/feedback` | the text you type, an email only if you give one. The last exchange (your request and the reply, which may contain code) is added only if you answer yes to "attach it" |
188
+
189
+ Never sent: your code, file contents, prompts, model replies, shell commands, file paths, argument values, API keys. `/feedback` and `free-code feedback "text"` work even with automatic reports off, because you are sending that message yourself. Failed sends are retried from a small local queue (max 50). Reports are read by the maintainers and used to fix tools and crashes.
190
+
191
+ ## Updating
192
+
193
+ `free-code update` runs the right upgrade for how you installed it: `uv tool upgrade`, `pipx upgrade`, or `pip install --upgrade` (the installer's private venv, pip and npm). Once a day, without delaying startup, free-code checks whether a newer release exists and prints one line if so; it never installs by itself. Turn the check off with `FREE_CODE_NO_UPDATE_CHECK=1` or `free-code config set update_check false` (it is also off when `CI` is set).
194
+
195
+ ## Tool manifest
196
+
197
+ The tool list comes from `https://free.ai/api/v1/code/manifest/`, cached for six hours and validated before use: HTTPS only, size-capped, strict schema, and tools are declarative calls to Free.ai API paths that can only save files inside your project. A manifest can add a tool, fix a tool's description or parameters, switch a broken tool off, and announce the newest release. It cannot add or replace local tools (shell, files, git), and an older manifest than the cached one is ignored. Offline, or on any error, the built-in set is used. Opt out with `FREE_CODE_NO_MANIFEST=1` or `free-code config set manifest false`. Only the version is sent in the request.
198
+
199
+ ## Cloud Tasks
200
+
201
+ Run a coding task on Free.ai's infrastructure instead of your machine: like a codex agent from the terminal. Requires an API key: run `free-code login` (free tier works).
202
+
203
+ ```bash
204
+ # Submit and watch (polls until done, prints the markdown report)
205
+ free-code cloud "Add rate limiting to the API" --repo https://github.com/you/project
206
+
207
+ # Pick the cloud model
208
+ free-code cloud "Refactor the auth module" --model deepseek-coder
209
+
210
+ # Fire and forget (you get an email when it finishes)
211
+ free-code cloud "Write integration tests" --no-watch
212
+
213
+ # Download the resulting code as a zip, unpacked into ./result
214
+ free-code cloud "Fix the flaky test suite" --download ./result
215
+
216
+ # List recent tasks
217
+ free-code tasks
218
+ ```
219
+
220
+ ## Configuration
221
+
222
+ Config is stored at `~/.free-code/config.yaml`.
223
+
224
+ ```bash
225
+ # Set your Free.ai token (get one at https://free.ai/account/)
226
+ free-code config set token sk-free-xxx
227
+
228
+ # Use your own API key (BYOK: no markup, use your own provider)
229
+ free-code config set provider openai
230
+ free-code config set api_key sk-xxx
231
+
232
+ # Choose a model
233
+ free-code config set model qwen7b
234
+
235
+ # Enable safe mode (confirm before file writes)
236
+ free-code config set safe_mode true
237
+ ```
238
+
239
+ ### Supported Providers
240
+
241
+ | Provider | Default Model | Free Tier |
242
+ |----------|--------------|-----------|
243
+ | **free.ai** (default) | Qwen 7B | 50K tokens/day |
244
+ | **openai** | GPT-4o | BYOK: no markup |
245
+ | **anthropic** | Claude Sonnet 4 | BYOK: no markup |
246
+ | **google** | Gemini 2.5 Pro | BYOK: no markup |
247
+ | **openrouter** | 346+ models | BYOK: no markup |
248
+
249
+ ## How It Works
250
+
251
+ 1. Scans your project (respects .gitignore)
252
+ 2. Builds a context map of your codebase
253
+ 3. Sends your request + relevant code context to the AI
254
+ 4. AI plans steps, reads/writes files, runs commands
255
+ 5. You review and approve changes (safe mode)
256
+
257
+ All file operations happen locally on your machine. The AI sees only what it needs.
258
+
259
+ ## Pricing
260
+
261
+ - **Anonymous**: 10K tokens/day (Qwen Coder only)
262
+ - **Free account**: 50K tokens/day (sign up at [free.ai](https://free.ai/signup/))
263
+ - **Paid plans**: From $5/month for 200K tokens ([pricing](https://free.ai/pricing/))
264
+ - **BYOK**: $0: bring your own API key, no markup
265
+
266
+ ## Links
267
+
268
+ - [Free.ai](https://free.ai): 400+ free AI tools
269
+ - [Web IDE](https://free.ai/coder/): Use in your browser
270
+ - [API Docs](https://free.ai/api/): Build on top of Free.ai
271
+ - [Compare vs Claude Code](https://free.ai/compare/coder-vs-claude-code/)
272
+ - [Compare vs Cursor](https://free.ai/compare/coder-vs-cursor/)
273
+
274
+ ## vs Competitors
275
+
276
+ | Feature | Free.ai Coder | Claude Code | OpenAI Codex | Cursor | GitHub Copilot |
277
+ |---------|--------------|-------------|--------------|--------|----------------|
278
+ | Free tier | 50K tokens/day | None ($20/mo) | None ($200/mo) | None ($20/mo) | None ($10/mo) |
279
+ | Self-hosted models | Yes (Qwen, DeepSeek) | No | No | No | No |
280
+ | BYOK (bring your own key) | Yes: $0 markup | No | No | Partial | No |
281
+ | Open source CLI | Yes (MIT) | No | No | No | No |
282
+ | Web IDE | Yes (free.ai/coder/) | No | Yes | Yes | No |
283
+ | Terminal access | Yes | Yes | Yes | Yes | No |
284
+ | 346+ models | Yes | Claude only | GPT only | Multiple | GPT only |
285
+ | Session sync (CLI ↔ web) | Yes | No | No | No | No |
286
+
287
+ ## BYOK (Bring Your Own Key)
288
+
289
+ Use your own API keys from any provider: zero markup, zero fees. Free.ai just proxies the request.
290
+
291
+ ```bash
292
+ # OpenAI
293
+ free-code config set provider openai
294
+ free-code config set api_key sk-proj-xxx
295
+
296
+ # Anthropic
297
+ free-code config set provider anthropic
298
+ free-code config set api_key sk-ant-xxx
299
+
300
+ # Google
301
+ free-code config set provider google
302
+ free-code config set api_key AIzaSyxxx
303
+
304
+ # OpenRouter (access 346+ models)
305
+ free-code config set provider openrouter
306
+ free-code config set api_key sk-or-xxx
307
+ ```
308
+
309
+ When using BYOK, requests go directly to the provider. No markup. No logging. Your key, your usage, your bill.
310
+
311
+ You can also set keys via environment variables:
312
+
313
+ ```bash
314
+ export FREE_CODE_PROVIDER=openai
315
+ export FREE_CODE_API_KEY=sk-proj-xxx
316
+ free-code
317
+ ```
318
+
319
+ ## Free.ai Ecosystem
320
+
321
+ - **[Free.ai](https://free.ai)**: 400+ free AI tools on the web
322
+ - **[Python SDK](https://github.com/muddyholdings/free-sdk)**: `pip install free-dot-ai`: use Free.ai from your code
323
+ - **[CLI Coder](https://github.com/muddyholdings/free-code)**: `pip install freeai-code`: AI coding in your terminal
324
+ - **[iOS App](https://free.ai/ios/)**: Native iPhone/iPad app
325
+ - **[Android App](https://free.ai/android/)**: Native Android app
326
+ - **[API Docs](https://free.ai/api/)**: Build on top of Free.ai
327
+ - **[Web IDE](https://free.ai/coder/)**: Code in your browser
328
+
329
+ ## License
330
+
331
+ MIT
@@ -0,0 +1,298 @@
1
+ # Free.ai Coder
2
+
3
+ Free AI coding assistant for your terminal. A free, open-source alternative to Claude Code, Cursor, and GitHub Copilot.
4
+
5
+ **[Website](https://free.ai/coder/)** | **[PyPI](https://pypi.org/project/freeai-code/)** | **[npm](https://www.npmjs.com/package/freeai-code)** | **[Web IDE](https://free.ai/coder/)**
6
+
7
+ ## Install
8
+
9
+ One line, nothing to set up first (no Python, no pip, no sudo). It uses [uv](https://docs.astral.sh/uv/) and installs it for you if missing.
10
+
11
+ ```bash
12
+ # macOS / Linux
13
+ curl -fsSL https://free.ai/install.sh | sh
14
+ ```
15
+
16
+ ```powershell
17
+ # Windows (PowerShell)
18
+ irm https://free.ai/install.ps1 | iex
19
+ ```
20
+
21
+ Re-run the same line to upgrade. Pin a version with `FREE_CODE_VERSION=0.1.4` (PowerShell: `$env:FREE_CODE_VERSION = "0.1.4"`). The scripts are in [`install/`](install/): they use uv, else pipx, else a private venv in `~/.free-code`, and put `free-code` in `~/.local/bin`.
22
+
23
+ Already have Python or Node?
24
+
25
+ ```bash
26
+ pip install freeai-code
27
+ npm install -g freeai-code
28
+ ```
29
+
30
+ ## First run
31
+
32
+ Run `free-code` in a project. The free anonymous tier works with no account.
33
+
34
+ To sign in, run `free-code login`. It opens your browser at free.ai; sign in or create an account there, press Approve, and the CLI receives a key automatically (stored in `~/.free-code/config.yaml`, mode 600). On a remote machine it prints the address and a short code instead, so you can approve from any device (`free-code login --no-browser`). When the anonymous daily limit is used up, the CLI offers the same sign-in on the spot. Prefer to paste a key or use your own provider? `free-code login --manual`.
35
+
36
+ On first run in a terminal it also asks once whether to send anonymous crash and tool-failure reports. The default is no. See [Feedback](#feedback-opt-in).
37
+
38
+ ## Quick Start
39
+
40
+ ```bash
41
+ # Interactive coding session in your project directory
42
+ cd your-project/
43
+ free-code
44
+
45
+ # Ask a one-shot question about your codebase
46
+ free-code ask "How does the auth system work?"
47
+
48
+ # Execute a task
49
+ free-code run "Add unit tests for the User model"
50
+
51
+ # Run a task in the Free.ai cloud (codex-style) and watch it
52
+ free-code cloud "Fix the failing CI on main" --repo https://github.com/you/project
53
+
54
+ # Initialize and scan codebase
55
+ free-code init
56
+ ```
57
+
58
+ ## Commands
59
+
60
+ | Command | Description |
61
+ |---------|-------------|
62
+ | `free-code` | Interactive coding session (alias: `free-code chat`). `-c` resumes the latest session, `--resume ID` a specific one |
63
+ | `free-code -p "task"` | Non-interactive: print the answer and exit (see [Scripts and CI](#scripts-and-ci)) |
64
+ | `free-code ask "question"` | One-shot question about the codebase |
65
+ | `free-code run "task"` | Execute a coding task |
66
+ | `free-code models` | Every model Free.ai serves, free tier first (`--free`, `--paid`, `--type image`, a search word) |
67
+ | `free-code tools` | The tools the agent has (local, platform, MCP) and what needs approval (`--refresh` fetches the server manifest) |
68
+ | `free-code mcp add/list/remove/tools/trust` | Use MCP servers such as sttai-mcp |
69
+ | `free-code sessions` | Saved sessions you can resume |
70
+ | `free-code login` / `logout` | Sign in through the browser / forget the key |
71
+ | `free-code update` | Upgrade through whatever installed it (`--check`, `--version X`, `--dry-run`) |
72
+ | `free-code feedback "text"` | Send feedback you type |
73
+ | `free-code config feedback on\|off\|status` | Opt-in automatic reports |
74
+ | `free-code cloud "task"` | Run a coding task in the Free.ai cloud (`--repo URL`, `--model`, `--no-watch`, `--download DIR`) |
75
+ | `free-code tasks` | List your recent cloud tasks |
76
+ | `free-code init` | Initialize config, scan codebase |
77
+ | `free-code config` | Show current configuration |
78
+ | `free-code config set key value` | Set a config value |
79
+
80
+ Inside a session: `/model` (picker), `/models`, `/tools`, `/sessions`, `/resume`, `/feedback`, `/update`, `/compact`, `/clear`, `/diff`, `/status`, `/test`, `/files`, `/repo`, `/help`.
81
+
82
+ ## Features
83
+
84
+ - File read/write with diff preview and approval gates
85
+ - Shell command execution (with confirmation in safe mode)
86
+ - Git integration (status, diff, commit, log), test runner auto-detection (pytest, jest, go test, cargo test)
87
+ - `web_fetch` to read docs and issues
88
+ - Platform tools that call Free.ai with your key (see below): image, speech, music and video generation saved into your project, audio transcription, OCR of screenshots and PDFs, web search with citations, translation of strings and whole i18n files
89
+ - MCP client (stdio and HTTP): use sttai-mcp, Claude Desktop style servers and others
90
+ - Model picker over everything Free.ai serves, honest about free tier versus paid
91
+ - Sessions saved locally and resumable
92
+ - Non-interactive mode with JSON output and exit codes for scripts and CI
93
+ - Opt-in feedback, and self-update with a once-a-day version notice
94
+ - Tools shipped from a server manifest, so new tools and tool fixes arrive without a release (offline falls back to the built-in set)
95
+ - Streaming output, context window optimization, repo map, .gitignore-aware discovery
96
+ - Session sync with [web](https://free.ai/coder/) and cloud tasks on Free.ai's GPUs
97
+
98
+ ## Platform tools
99
+
100
+ The model can call these. They use your Free.ai key (or the free anonymous tier) and the public API at api.free.ai.
101
+
102
+ | Tool | What it does | Approval in safe mode |
103
+ |------|--------------|-----------------------|
104
+ | `generate_image` | Text to image, saved to a path in your project | yes (writes a file) |
105
+ | `generate_speech` | Text to speech audio, saved to your project | yes |
106
+ | `generate_music` | Short music clip, saved to your project | yes |
107
+ | `generate_video` | Short video clip, saved to your project (slow) | yes |
108
+ | `transcribe_audio` | Speech to text for an audio or video file | yes (uploads the file) |
109
+ | `ocr_image` | Text out of an image or PDF | yes (uploads the file) |
110
+ | `web_search` | Cited web answer plus source links | no |
111
+ | `translate_text` | Translate a short string | no |
112
+ | `translate_file` | Translate a JSON or YAML locale file, protecting `{0}`, `{name}`, `%s` placeholders; a string whose placeholders change is left in the source language and reported | writes the new file |
113
+
114
+ Free tier versus paid: `free-code models` marks each model. "free tier" means no token price (Free.ai's self-hosted models, within the daily limits); "paid" means billed in tokens and it needs a key with balance. Self-hosted image, video and audio models list no per-token price and count against the daily free allowance.
115
+
116
+ ## MCP servers
117
+
118
+ ```bash
119
+ pip install sttai-mcp
120
+ free-code mcp add stt-ai sttai-mcp --env STT_API_KEY='${STT_API_KEY}'
121
+ free-code mcp tools stt-ai # check it connects
122
+ free-code # its tools appear as mcp__stt_ai__<tool>
123
+ ```
124
+
125
+ `${NAME}` in `--env` values is read from your own environment, so no secret is written to disk. Servers live in `~/.free-code/mcp.json` (same `mcpServers` shape as Claude Desktop; `--url https://...` adds an HTTP server). A project can ship `.free-code/mcp.json`, but opening a repository must not start programs, so it is ignored until you run `free-code mcp trust` and it re-prompts if the file changes. MCP tools ask for approval in safe mode.
126
+
127
+ ## Scripts and CI
128
+
129
+ ```bash
130
+ free-code -p "summarize the failing tests" --yes # plain answer on stdout
131
+ free-code run "bump the version" --json --yes # one JSON object
132
+ free-code -p "review this diff: $(git diff)" # prompt built by your shell
133
+ ```
134
+
135
+ `--json` prints `{"ok", "response", "error", "tools": [{"tool","ok"}], "model", "session", "needs_approval"}`. Exit codes: 0 done, 1 failed (API or agent error), 3 an edit or command needed approval and none was given, 130 interrupted. Without a terminal nothing is ever approved implicitly: pass `--yes` to allow edits. `--yes` still refuses commands that match the dangerous list (`rm -rf`, `git reset --hard`, ...). `--max-steps`, `--model` and `--no-mcp` are available everywhere.
136
+
137
+ ## Feedback (opt-in)
138
+
139
+ Off until you say yes. First run in a terminal asks once (Enter means no). Change it any time:
140
+
141
+ ```bash
142
+ free-code config feedback on|off|status
143
+ ```
144
+
145
+ `FREE_CODE_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` force it off. `FREE_CODE_TELEMETRY_DRYRUN=1` prints every payload to stderr instead of sending it.
146
+
147
+ When on, exactly these can be sent to `https://free.ai/api/v1/code/telemetry/`, anonymously (no account, and the server stores no IP):
148
+
149
+ | Event | Contents |
150
+ |-------|----------|
151
+ | Crash | free-code version, OS name, Python version, install method, the exception class, free-code's own stack frames (file, line, function), and the exception message with quoted text, paths, numbers and long tokens replaced by placeholders |
152
+ | Tool failure | tool name, an error class (`not_found`, `timeout`, `rate_limited`...), model id, and the shape of the arguments: names and a type or size bucket such as `str:1-80`, never values. MCP tool names are not sent |
153
+ | Rating | thumbs up or down after a task (asked after the first task, then every fifth), plus a comment only if you type one |
154
+ | `/feedback` | the text you type, an email only if you give one. The last exchange (your request and the reply, which may contain code) is added only if you answer yes to "attach it" |
155
+
156
+ Never sent: your code, file contents, prompts, model replies, shell commands, file paths, argument values, API keys. `/feedback` and `free-code feedback "text"` work even with automatic reports off, because you are sending that message yourself. Failed sends are retried from a small local queue (max 50). Reports are read by the maintainers and used to fix tools and crashes.
157
+
158
+ ## Updating
159
+
160
+ `free-code update` runs the right upgrade for how you installed it: `uv tool upgrade`, `pipx upgrade`, or `pip install --upgrade` (the installer's private venv, pip and npm). Once a day, without delaying startup, free-code checks whether a newer release exists and prints one line if so; it never installs by itself. Turn the check off with `FREE_CODE_NO_UPDATE_CHECK=1` or `free-code config set update_check false` (it is also off when `CI` is set).
161
+
162
+ ## Tool manifest
163
+
164
+ The tool list comes from `https://free.ai/api/v1/code/manifest/`, cached for six hours and validated before use: HTTPS only, size-capped, strict schema, and tools are declarative calls to Free.ai API paths that can only save files inside your project. A manifest can add a tool, fix a tool's description or parameters, switch a broken tool off, and announce the newest release. It cannot add or replace local tools (shell, files, git), and an older manifest than the cached one is ignored. Offline, or on any error, the built-in set is used. Opt out with `FREE_CODE_NO_MANIFEST=1` or `free-code config set manifest false`. Only the version is sent in the request.
165
+
166
+ ## Cloud Tasks
167
+
168
+ Run a coding task on Free.ai's infrastructure instead of your machine: like a codex agent from the terminal. Requires an API key: run `free-code login` (free tier works).
169
+
170
+ ```bash
171
+ # Submit and watch (polls until done, prints the markdown report)
172
+ free-code cloud "Add rate limiting to the API" --repo https://github.com/you/project
173
+
174
+ # Pick the cloud model
175
+ free-code cloud "Refactor the auth module" --model deepseek-coder
176
+
177
+ # Fire and forget (you get an email when it finishes)
178
+ free-code cloud "Write integration tests" --no-watch
179
+
180
+ # Download the resulting code as a zip, unpacked into ./result
181
+ free-code cloud "Fix the flaky test suite" --download ./result
182
+
183
+ # List recent tasks
184
+ free-code tasks
185
+ ```
186
+
187
+ ## Configuration
188
+
189
+ Config is stored at `~/.free-code/config.yaml`.
190
+
191
+ ```bash
192
+ # Set your Free.ai token (get one at https://free.ai/account/)
193
+ free-code config set token sk-free-xxx
194
+
195
+ # Use your own API key (BYOK: no markup, use your own provider)
196
+ free-code config set provider openai
197
+ free-code config set api_key sk-xxx
198
+
199
+ # Choose a model
200
+ free-code config set model qwen7b
201
+
202
+ # Enable safe mode (confirm before file writes)
203
+ free-code config set safe_mode true
204
+ ```
205
+
206
+ ### Supported Providers
207
+
208
+ | Provider | Default Model | Free Tier |
209
+ |----------|--------------|-----------|
210
+ | **free.ai** (default) | Qwen 7B | 50K tokens/day |
211
+ | **openai** | GPT-4o | BYOK: no markup |
212
+ | **anthropic** | Claude Sonnet 4 | BYOK: no markup |
213
+ | **google** | Gemini 2.5 Pro | BYOK: no markup |
214
+ | **openrouter** | 346+ models | BYOK: no markup |
215
+
216
+ ## How It Works
217
+
218
+ 1. Scans your project (respects .gitignore)
219
+ 2. Builds a context map of your codebase
220
+ 3. Sends your request + relevant code context to the AI
221
+ 4. AI plans steps, reads/writes files, runs commands
222
+ 5. You review and approve changes (safe mode)
223
+
224
+ All file operations happen locally on your machine. The AI sees only what it needs.
225
+
226
+ ## Pricing
227
+
228
+ - **Anonymous**: 10K tokens/day (Qwen Coder only)
229
+ - **Free account**: 50K tokens/day (sign up at [free.ai](https://free.ai/signup/))
230
+ - **Paid plans**: From $5/month for 200K tokens ([pricing](https://free.ai/pricing/))
231
+ - **BYOK**: $0: bring your own API key, no markup
232
+
233
+ ## Links
234
+
235
+ - [Free.ai](https://free.ai): 400+ free AI tools
236
+ - [Web IDE](https://free.ai/coder/): Use in your browser
237
+ - [API Docs](https://free.ai/api/): Build on top of Free.ai
238
+ - [Compare vs Claude Code](https://free.ai/compare/coder-vs-claude-code/)
239
+ - [Compare vs Cursor](https://free.ai/compare/coder-vs-cursor/)
240
+
241
+ ## vs Competitors
242
+
243
+ | Feature | Free.ai Coder | Claude Code | OpenAI Codex | Cursor | GitHub Copilot |
244
+ |---------|--------------|-------------|--------------|--------|----------------|
245
+ | Free tier | 50K tokens/day | None ($20/mo) | None ($200/mo) | None ($20/mo) | None ($10/mo) |
246
+ | Self-hosted models | Yes (Qwen, DeepSeek) | No | No | No | No |
247
+ | BYOK (bring your own key) | Yes: $0 markup | No | No | Partial | No |
248
+ | Open source CLI | Yes (MIT) | No | No | No | No |
249
+ | Web IDE | Yes (free.ai/coder/) | No | Yes | Yes | No |
250
+ | Terminal access | Yes | Yes | Yes | Yes | No |
251
+ | 346+ models | Yes | Claude only | GPT only | Multiple | GPT only |
252
+ | Session sync (CLI ↔ web) | Yes | No | No | No | No |
253
+
254
+ ## BYOK (Bring Your Own Key)
255
+
256
+ Use your own API keys from any provider: zero markup, zero fees. Free.ai just proxies the request.
257
+
258
+ ```bash
259
+ # OpenAI
260
+ free-code config set provider openai
261
+ free-code config set api_key sk-proj-xxx
262
+
263
+ # Anthropic
264
+ free-code config set provider anthropic
265
+ free-code config set api_key sk-ant-xxx
266
+
267
+ # Google
268
+ free-code config set provider google
269
+ free-code config set api_key AIzaSyxxx
270
+
271
+ # OpenRouter (access 346+ models)
272
+ free-code config set provider openrouter
273
+ free-code config set api_key sk-or-xxx
274
+ ```
275
+
276
+ When using BYOK, requests go directly to the provider. No markup. No logging. Your key, your usage, your bill.
277
+
278
+ You can also set keys via environment variables:
279
+
280
+ ```bash
281
+ export FREE_CODE_PROVIDER=openai
282
+ export FREE_CODE_API_KEY=sk-proj-xxx
283
+ free-code
284
+ ```
285
+
286
+ ## Free.ai Ecosystem
287
+
288
+ - **[Free.ai](https://free.ai)**: 400+ free AI tools on the web
289
+ - **[Python SDK](https://github.com/muddyholdings/free-sdk)**: `pip install free-dot-ai`: use Free.ai from your code
290
+ - **[CLI Coder](https://github.com/muddyholdings/free-code)**: `pip install freeai-code`: AI coding in your terminal
291
+ - **[iOS App](https://free.ai/ios/)**: Native iPhone/iPad app
292
+ - **[Android App](https://free.ai/android/)**: Native Android app
293
+ - **[API Docs](https://free.ai/api/)**: Build on top of Free.ai
294
+ - **[Web IDE](https://free.ai/coder/)**: Code in your browser
295
+
296
+ ## License
297
+
298
+ MIT
@@ -1,3 +1,3 @@
1
1
  """Free.ai Coder CLI — Free AI coding assistant."""
2
2
 
3
- __version__ = "0.1.3"
3
+ __version__ = "0.2.0"