A terminal-based AI coding agent powered by Anthropic's Claude and OpenAI models, designed to assist with coding tasks directly from your terminal.
This repository was built as part of my "Let's Build Cursor" AI Coding tutorial series.
See the Final Working Coding Agent Add Tests
I built this mostly for educational purposes and have not tested these steps! Please let me know if these work for you and ideally submit a PR to update these instructions. 🙏
- Node.js (v18 or higher)
- npm or yarn
- API key for Anthropic Claude and OpenAI (OpenAI key is optional, only used for semantic search embeddings)
# Install globally
npm install -g forq-cli
# Verify installation
forq --version
# Start the REPL
forq repl# Clone the repository
git clone https://github.com/kleneway/forq-cli.git
cd forq-cli
# Install dependencies
npm install
# Build the project
npm run build
# Install globally
npm run global-install
# OR
npm install -g .If you encounter issues with global installation:
-
Command not found after installation:
-
Check your global npm directory is in your PATH:
# Find npm global prefix npm config get prefix # Make sure the bin directory under this path is in your PATH echo $PATH
-
Add the npm bin directory to your PATH if needed:
# For bash (add to .bashrc or .bash_profile) export PATH="$(npm config get prefix)/bin:$PATH" # For zsh (add to .zshrc) export PATH="$(npm config get prefix)/bin:$PATH"
-
-
Permission issues:
# Install with sudo (if necessary) sudo npm install -g forq-cli -
Running without installing:
# Run directly using npx npx forq-cli repl # Or use the provided shell wrapper (from source) ./bin/forq repl
-
Using the diagnostic tool:
# Check installation and environment forq diagnose
Before using Forq, you need to set up your API keys:
- Create a
.envfile in your project root or copy from the example:
cp .env.example .env- Add your API keys to the
.envfile:
ANTHROPIC_API_KEY=your-anthropic-api-key
OPENAI_API_KEY=your-openai-api-key
- Initialize the configuration:
forq config --initForq supports both global and project-specific configurations:
- Global configuration:
~/.forqrc.json - Project configuration:
.forqrc.jsonin your project directory
View current configuration:
# View global config
forq config --global
# View project config
forq config --projectSet configuration values:
# Set API key in global config
forq config --global --key apiKeys.anthropic --value "your-api-key"
# Set preferred model
forq config --global --key preferences.model --value "claude-3-7-sonnet-20250219"# Start an interactive REPL session
forq replWithin the REPL, you can use these special commands:
/help- Show available commands/clear- Clear the conversation history/exit- Exit the REPL
# View logs
forq log --type actions
forq log --type error --lines 50
# View and edit configuration
forq config --global
forq config --project --key allowedTools --value '["bash", "listDir"]'You can add project-specific instructions by creating a FORQ.md file in your project root. This file will be read when Forq is started in the project directory, providing context to the AI about your project.
Example of using Forq to analyze code:
# In your project directory
forq repl
> Analyze the current project structure and suggest improvementsFor more detailed documentation, see the docs directory:
MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request