ForgeCodeCLI
An agentic, file-aware command-line tool that lets you manage and modify your codebase using natural language — powered by LLMs.
It acts as a safe, deterministic AI agent that can read files, create/delete directories, and write code only through explicit tools, not raw hallucination.
Features
- ✅ Agentic workflow - LLM decides actions, CLI executes them safely
- ✅ File operations - Read, list, create, write, delete, move files & directories
- ✅ Undo support - Reverse the last file operation with
undo - ✅ Multi-provider LLMs - Gemini, OpenAI (GPT), Anthropic (Claude), Groq
- ✅ Model selection - Choose specific models for each provider
- ✅ Secure storage - API keys stored in system keyring (no env vars)
- ✅ Deterministic - Rule-based execution with validation
- ✅ Interactive CLI - Real-time agent feedback
Installation
Requires Python 3.9+
pip install forgecodecli
Optional: For Anthropic (Claude) support, install with the anthropic extra:
pip install forgecodecli[anthropic]
Or install later when prompted during setup.
Quick Start
Initialize (one-time setup)
forgecodecli init
You will be prompted to:
-
Select LLM Provider
1) Google Gemini 2) OpenAI 3) Anthropic (Claude) 4) Groq -
Select Model (varies by provider)
- Gemini:
gemini-2.5-flash,gemini-2.0-flash,gemini-1.5-pro - OpenAI:
gpt-4o,gpt-4-turbo,gpt-3.5-turbo - Claude:
claude-3-5-sonnet,claude-3-opus,claude-3-haiku - Groq:
llama-3.3-70b,mixtral-8x7b,gemma2-9b-it
- Gemini:
-
Enter API Key (stored securely in system keyring)
Start the agent
forgecodecli
You are now in interactive agent mode. Example commands:
create a folder src/app with main.py that prints "Hello World"
read the config.py file
list all files in src
delete old_backup folder
move test.py to tests/test.py
undo
Type help for built-in commands, or press Ctrl + C to exit.
Reset Configuration
To remove all configuration and API keys:
forgecodecli reset
Security
- API keys are stored using the system keyring
- No API keys are written to config files or environment variables
- Config files contain only non-sensitive metadata
How It Works
- You enter a natural language command
- The LLM decides the next valid action
- ForgeCodeCLI executes the action with validation
- The agent receives feedback and responds
- Process repeats until agent provides an answer
Safety mechanisms:
- Action limit of 2 per request (prevents infinite loops)
- Conversation context maintained for agent awareness
- All operations logged and reversible with
undo - Strict tool validation
Supported Actions
The agent can execute these operations:
File Operations:
| Action | Description |
|---|---|
read_file |
Read and display file contents |
list_files |
List files in a directory |
create_dir |
Create new directories |
write_file |
Create and write files |
delete_file |
Delete files permanently |
delete_dir |
Delete directories |
move_file |
Move or rename files |
move_dir |
Move or rename directories |
undo |
Reverse the last operation |
Git Operations:
| Action | Description |
|---|---|
git_init |
Initialize git repository |
git_add |
Stage files for commit |
git_commit |
Commit staged changes |
git_push |
Push to remote repository |
git_set_origin |
Set remote repository URL |
git_status |
Show repository status |
git_log |
View commit history |
git_branch |
Manage branches |
git_pull |
Pull from remote |
git_clone |
Clone a repository |
All actions are executed safely with validation and error handling.
What's Available
- File operations (read, list, create, write, delete, move)
- Undo functionality - Stack-based operation reversal
- Git operations - init, add, commit, push, pull, status, log, branch, clone, set_origin
- Multi-provider support - Gemini, OpenAI, Anthropic, Groq
- Model selection - Choose specific models per provider
- Auto-install SDKs - Anthropic SDK installs on demand
- Proper conversation flow with max actions per request
Coming Soon
- Copy files/directories
- Full undo/redo history (not just last operation)
- File search capabilities
- Code generation templates
- Batch operations
- Backup/snapshot functionality
License
MIT License
Author
Built by Sudhanshu
Metadata
Release files for forgecodecli 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| forgecodecli-2.0.0.tar.gz | 14.3 kB | Without provenance | Details for forgecodecli-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| forgecodecli-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for forgecodecli-2.0.0-py3-none-any.whl |
Total release size: 28.4 kB
Release files / forgecodecli-2.0.0.tar.gz
| Download URL | forgecodecli-2.0.0.tar.gz |
|---|---|
| Size | 14.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d72ebe8ce687270613cdc36ac7af2cbe60052c876a56734c56359cbc1184bd34
|
|
BLAKE2b-256 checksum How to use checksums |
44813c345012cf842a2c0f62610bc87c3e790e62b6e5fd42141e920fefb8f8ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / forgecodecli-2.0.0-py3-none-any.whl
| Download URL | forgecodecli-2.0.0-py3-none-any.whl |
|---|---|
| Size | 14.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6ab2f5d6b3fd5298c7ec89822696325920e4037e6863a1db9cc78be92b0a8d87
|
|
BLAKE2b-256 checksum How to use checksums |
8f46094ea590d5f17db72cffe4eb1c730c377f66867df07ac71d59b9ec08cebc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for forgecodecli 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.