Skip to content
Back to search

forgecode

SkillWorks with Claude CodeGitHub

AI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300+ models

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tailcallhq/forgecode with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tailcallhq/forgecode'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tailcallhq--forgecode/badge.svg)](/listings/tailcallhq--forgecode)

HTML

<a href="/listings/tailcallhq--forgecode"><img src="/api/listings/tailcallhq--forgecode/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

To get started with Forge, run the command below:

curl -fsSL https://forgecode.dev/cli | sh

On first run, Forge will guide you through setting up your AI provider credentials using the interactive login flow. Alternatively, you can configure providers beforehand:

# Configure your provider credentials interactively
forge provider login

# Then start Forge
forge

That's it! Forge is now ready to assist you with your development tasks.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,159 lines · 3 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">⚒️ Forge: AI-Enhanced Terminal Development Environment</h1>
  2. <p align="center">A comprehensive coding agent that integrates AI capabilities with your development environment</p>
  3. <p align="center"><code>curl -fsSL https://forgecode.dev/cli | sh</code></p>
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 4 on GitHub
  4. [![CI Status](https://img.shields.io/github/actions/workflow/status/tailcallhq/forgecode/ci.yml?style=for-the-badge)](https://github.com/tailcallhq/forgecode/actions)
  5. [![GitHub Release](https://img.shields.io/github/v/release/tailcallhq/forgecode?style=for-the-badge)](https://github.com/tailcallhq/forgecode/releases)
  6. [![Discord](https://img.shields.io/discord/1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https://discord.gg/kRZBPpkgwq)
  7. [![CLA assistant](https://cla-assistant.io/readme/badge/tailcallhq/forgecode?style=for-the-badge)](https://cla-assistant.io/tailcallhq/forgecode)
  8. ![Code-Forge Demo](https://assets.antinomy.ai/images/forge_demo_2x.gif)
  9. ---
  10. <details>
  11. <summary><strong>Table&nbsp;of&nbsp;Contents</strong></summary>
  12. - [Quickstart](#quickstart)
  13. - [Usage Examples](#usage-examples)
  14. - [Why Forge?](#why-forge)
  15. - [How Forge Works: Three Modes](#how-forge-works-three-modes)
  16. - [Interactive Mode (TUI)](#interactive-mode-tui)
  17. - [One-Shot CLI Mode](#one-shot-cli-mode)
  18. - [ZSH Plugin Mode (`:` prefix)](#zsh-plugin-mode--prefix)
  19. - [ZSH Plugin: The `:` Prefix System](#zsh-plugin-the--prefix-system)
  20. - [Agents](#agents)
  21. - [Sending Prompts](#sending-prompts)
  22. - [Attaching Files](#attaching-files)
  23. - [Conversation Management](#conversation-management)
  24. - [Git Integration](#git-integration)
  25. - [Shell Command Tools](#shell-command-tools)
  26. - [Session & Configuration](#session--configuration)
  27. - [Skills](#skills)
  28. - [Customizing Agent Behavior](#customizing-agent-behavior)
  29. - [Semantic Search (Workspace)](#semantic-search-workspace)
  30. - [Quick Reference: All `:` Commands](#quick-reference-all--commands)
  31. - [Command-Line Options](#command-line-options)
  32. - [Advanced Configuration](#advanced-configuration)
  33. - [Provider Configuration](#provider-configuration)
  34. - [Managing Provider Credentials](#managing-provider-credentials)
  35. - [Deprecated: Environment Variables](#deprecated-environment-variables)
  36. - [forge.yaml Configuration Options](#forgeyaml-configuration-options)
  37. - [Environment Variables](#environment-variables)
  38. - [MCP Configuration](#mcp-configuration)
  39. - [Example Use Cases](#example-use-cases)
  40. - [Usage in Multi-Agent Workflows](#usage-in-multi-agent-workflows)
  41. - [Documentation](#documentation)
  42. - [Community](#community)
  43. - [Support Us](#support-us)
  44. </details>
  45. ---
  46. ## Quickstart
  47. To get started with Forge, run the command below:
  48. ```bash
  49. curl -fsSL https://forgecode.dev/cli | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 60 on GitHub
  50. ```
  51. On first run, Forge will guide you through setting up your AI provider credentials using the interactive login flow. Alternatively, you can configure providers beforehand:
  52. ```bash
  53. # Configure your provider credentials interactively
  54. forge provider login
  55. # Then start Forge
  56. forge
  57. ```
  58. That's it! Forge is now ready to assist you with your development tasks.
  59. ## Usage Examples
  60. Forge can be used in different ways depending on your needs. Here are some common usage patterns:
  61. <details>
  62. <summary><strong>Code Understanding</strong></summary>
  63. ```
  64. > Can you explain how the authentication system works in this codebase?
  65. ```
  66. Forge will analyze your project's structure, identify authentication-related files, and provide a detailed explanation of the authentication flow, including the relationships between different components.
  67. </details>
  68. <details>
  69. <summary><strong>Implementing New Features</strong></summary>
  70. ```
  71. > I need to add a dark mode toggle to our React application. How should I approach this?
  72. ```
  73. Forge will suggest the best approach based on your current codebase, explain the steps needed, and even scaffold the necessary components and styles for you.
  74. </details>
  75. <details>
  76. <summary><strong>Debugging Assistance</strong></summary>
  77. ```
  78. > I'm getting this error: "TypeError: Cannot read property 'map' of undefined". What might be causing it?
  79. ```
  80. Forge will analyze the error, suggest potential causes based on your code, and propose different solutions to fix the issue.
  81. </details>
  82. <details>
  83. <summary><strong>Code Reviews</strong></summary>
  84. ```
  85. > Please review the code in src/components/UserProfile.js and suggest improvements
  86. ```
  87. Forge will analyze the code, identify potential issues, and suggest improvements for readability, performance, security, and maintainability.
  88. </details>
  89. <details>
  90. <summary><strong>Learning New Technologies</strong></summary>
  91. ```
  92. > I want to integrate GraphQL into this Express application. Can you explain how to get started?
  93. ```
  94. Forge will provide a tailored tutorial on integrating GraphQL with Express, using your specific project structure as context.
  95. </details>
  96. <details>
  97. <summary><strong>Database Schema Design</strong></summary>
  98. ```
  99. > I need to design a database schema for a blog with users, posts, comments, and categories
  100. ```
  101. Forge will suggest an appropriate schema design, including tables/collections, relationships, indexes, and constraints based on your project's existing database technology.
  102. </details>
  103. <details>
  104. <summary><strong>Refactoring Legacy Code</strong></summary>
  105. ```
  106. > Help me refactor this class-based component to use React Hooks
  107. ```
  108. Forge can help modernize your codebase by walking you through refactoring steps and implementing them with your approval.
  109. </details>
  110. <details>
  111. <summary><strong>Git Operations</strong></summary>
  112. ```
  113. > I need to merge branch 'feature/user-profile' into main but there are conflicts
  114. ```
  115. Forge can guide you through resolving git conflicts, explaining the differences and suggesting the best way to reconcile them.
  116. </details>
  117. ## Why Forge?
  118. Forge is designed for developers who want to enhance their workflow with AI assistance while maintaining full control over their development environment.
  119. - **Zero configuration** - Just add your API key and you're ready to go
  120. - **Seamless integration** - Works right in your terminal, where you already work
  121. - **Multi-provider support** - Use OpenAI, Anthropic, or other LLM providers
  122. - **Secure by design** - Restricted shell mode limits file system access and prevents unintended changes
  123. - **Open-source** - Transparent, extensible, and community-driven
  124. Forge helps you code faster, solve complex problems, and learn new technologies without leaving your terminal.
  125. ---
  126. ## How Forge Works: Three Modes
  127. Forge has three distinct ways to use it. Understanding this distinction upfront will save you confusion.
  128. ### Interactive Mode (TUI)
  129. Running `forge` with no arguments starts the interactive terminal UI, a persistent session where you type prompts and the AI responds in a conversational loop. This is the primary way to do multi-step work.
  130. ```bash
  131. forge # Start a new interactive session
  132. forge conversation resume <id> # Resume a specific saved conversation in interactive mode
  133. forge --conversation-id <id> # Same: resume conversation by ID
  134. forge --agent <agent-id> # Start interactive session with a specific agent
  135. forge -C /path/to/project # Start in a specific directory
  136. forge --sandbox experiment-name # Create an isolated git worktree + branch, then start there
  137. ```
  138. Once inside interactive mode, type your prompt and press Enter. Forge reads files, writes patches, runs commands, and maintains context across the whole session.
  139. ### One-Shot CLI Mode
  140. Pass `-p` (or `--prompt`) to run a single prompt and exit. Forge does the work and returns to your shell. Useful for scripts, piping output, or quick tasks.
  141. ```bash
  142. forge -p "Explain the purpose of src/main.rs"
  143. forge -p "Add error handling to the parse() function in lib.rs"
  144. echo "What does this do?" | forge # Pipe input as the prompt
  145. forge commit # Generate an AI commit message and commit (exits when done)
  146. forge commit --preview # Generate commit message, print it, then exit
  147. forge suggest "find large log files" # Translate natural language to a shell command, then exit
  148. ```
  149. > **Note:** `forge conversation resume <id>` opens the interactive TUI. It does **not** just print a message and exit. If you run it and see the cursor waiting, you are inside the interactive session. Type your prompt or press `Ctrl+C` to exit.
  150. ### ZSH Plugin Mode (`:` prefix)
  151. Install the ZSH plugin once with `forge setup`, then use `:` commands directly at your shell prompt without ever typing `forge`. This is the fastest mode for day-to-day development: send prompts, switch conversations, commit, and suggest commands without leaving your shell.
  152. ```zsh
  153. : refactor the auth module # Send a prompt to the active agent
  154. :commit # AI-powered git commit
  155. :suggest "find large log files" # Translate description → shell command in your buffer
  156. :conversation # Browse saved conversations with interactive picker
  157. ```
  158. See the full [ZSH Plugin reference below](#zsh-plugin-the--prefix-system) for all commands and aliases.
  159. ---
  160. ## ZSH Plugin: The `:` Prefix System
  161. When you install the ZSH plugin (`forge setup`), you get a `:` prefix command system at your shell prompt. This is the fastest way to use Forge during normal development; you never leave your shell.
  162. **How it works:** Lines starting with `:` are intercepted before the shell sees them and routed to Forge. Everything else runs normally.
  163. ```zsh
  164. : <prompt> # Send a prompt to the active agent
  165. :sage <prompt> # Send a prompt to a specific agent by name (sage, muse, forge, or any custom agent)
  166. :agent <name> # Switch the active agent; opens interactive picker if no name given
  167. ```
  168. ### Agents
  169. Forge ships with three built-in agents, each with a different role:
  170. | Agent | Alias | Purpose | Modifies files? |
  171. |---|---|---|---|
  172. | `forge` | (default) | Implementation: builds features, fixes bugs, and runs tests | Yes |
  173. | `sage` | `:ask` | Research: maps architecture, traces data flow, and reads code | No |
  174. | `muse` | `:plan` | Planning: analyzes structure and writes implementation plans to `plans/` | No |
  175. ### Sending Prompts
  176. ```zsh
  177. : refactor the auth module to use the new middleware
  178. :sage how does the caching layer work? # sage = read-only research agent
  179. :muse design a deployment strategy # muse = planning agent (writes to plans/)
  180. :ask how does X work? # alias for :sage
  181. :plan create a migration plan # alias for :muse
  182. ```
  183. The agent context persists. Typing `:sage` alone (no prompt text) switches the active agent to sage for all subsequent `: <prompt>` commands.
  184. ### Attaching Files
  185. Type `@` in a prompt, then press Tab to fuzzy-search and select files. The path is inserted as `@[filename]` and attached as context to the AI.
  186. ```zsh
  187. : review this code @[src/auth.rs] @[tests/auth_test.rs]
  188. ```
  189. ### Conversation Management
  190. Forge saves every conversation. You can switch between them like switching directories.
  191. ```zsh
  192. :new # Start a fresh conversation (saves current for :conversation -)
  193. :new <initial prompt> # Start a new conversation and immediately send a prompt
  194. :conversation # Open interactive picker: browse and switch conversations with preview
  195. :conversation <id> # Switch directly to a conversation by ID
  196. :conversation - # Toggle between current and previous conversation (like cd -)
  197. :clone # Branch the current conversation (try a different direction)
  198. :clone <id> # Clone a specific conversation by ID
  199. :rename <name> # Rename the current conversation
  200. :conversation-rename # Rename a conversation via interactive picker
  201. :retry # Retry the last prompt (useful if the AI misunderstood)
  202. :copy # Copy the last AI response to clipboard as markdown
  203. :dump # Export conversation as JSON
  204. :dump html # Export conversation as formatted HTML
  205. :compact # Manually compact context to free up token budget
  206. ```
  207. ### Git Integration
  208. ```zsh
  209. :commit # AI reads your diff, writes a commit message, and commits immediately
  210. :commit <context> # Same, but pass extra context: :commit fix typo in readme
  211. :commit-preview # AI generates the message and puts "git commit -m '...'" in your buffer
  212. # so you can review/edit the message before pressing Enter
  213. ```
  214. ### Shell Command Tools
  215. ```zsh
  216. :suggest <description> # Translate natural language to a shell command and put it in your buffer
  217. :edit # Open $EDITOR to compose a complex multi-line prompt, then send it
  218. ```
  219. ### Session & Configuration
  220. Some commands change settings for the current session only. Others persist to your config file (`~/forge/.forge.toml`). The distinction matters:
  221. ```zsh
  222. # Session-only (reset when you close the terminal; not saved to config)
  223. :model <model-id> # Change model for this session only
  224. :reasoning-effort <level> # Set reasoning effort: none/minimal/low/medium/high/xhigh/max
  225. :agent <id> # Switch active agent for this session
  226. # Persistent (saved to config file)
  227. :config-model <model-id> # Set default model globally (alias: :cm)
  228. :config-provider # Switch provider globally (alias: :provider, :p)
  229. :config-reasoning-effort <lvl> # Set default reasoning effort globally (alias: :cre)
  230. :config-commit-model <id> # Set model used for :commit (alias: :ccm)
  231. :config-suggest-model <id> # Set model used for :suggest (alias: :csm)
  232. :config-reload # Reset session overrides back to global config (alias: :cr)
  233. # View & edit config
  234. :info # Show current session info (model, agent, conversation ID)
  235. :config # Display effective resolved configuration in TOML format
  236. :config-edit # Open config file in $EDITOR (alias: :ce)
  237. :tools # List available tools for the current agent
  238. :skill # List available skills
  239. ```
  240. ### Skills
  241. Skills are reusable workflows the AI can invoke as tools. Forge ships three built-in skills:
  242. - **`create-skill`**: scaffold a new custom skill
  243. - **`execute-plan`**: execute a plan file from `plans/`
  244. - **`github-pr-description`**: generate a PR description from your diff
  245. Use `:skill` to list available skills. The AI invokes them automatically when relevant, or you can ask explicitly: `: generate a PR description using the github-pr-description skill`.
  246. **Custom skills** live in `SKILL.md` files with YAML front-matter. Precedence (highest first):
  247. | Location | Path | Scope |
  248. |---|---|---|
  249. | Project-local | `.forge/skills/<name>/SKILL.md` | This project only |
  250. | Global | `~/forge/skills/<name>/SKILL.md` | All projects |
  251. | Built-in | Embedded in binary | Always available |
  252. Project-local skills override global ones, which override built-in ones. To scaffold a new skill, ask: `: create a new skill`.
  253. ### Customizing Agent Behavior
  254. **`AGENTS.md`:** Create this file in your project root (or `~/forge/AGENTS.md` globally) to give all agents persistent instructions such as coding conventions, commit message style, and things to avoid. Forge reads it automatically at the start of every conversation.
  255. **Custom agents:** Place a `.md` file with YAML front-matter in `.forge/agents/` (project) or `~/forge/agents/` (global) to define additional agents with their own models, tools, and system prompts. Project-local agents override global ones. The built-in agent files in `crates/forge_repo/src/agents/` are good examples of the format.
  256. **Custom commands:** Place YAML files in `.forge/commands/` (project) or `~/forge/commands/` (global) to define shortcut commands available via `:commandname`. Commands can also be defined inline in `forge.yaml` under the `commands:` key.
  257. ### Semantic Search (Workspace)
  258. ```zsh
  259. :sync # Index your codebase for semantic search
  260. :workspace-init # Initialize workspace for indexing
  261. :workspace-status # Show indexing status
  262. :workspace-info # Show workspace details
  263. ```
  264. After running `:sync`, the AI can search your codebase by meaning rather than exact text matches. Indexing sends file content to the workspace server, which defaults to `https://api.forgecode.dev`. Set `FORGE_WORKSPACE_SERVER_URL` to override this if self-hosting.
  265. ### Quick Reference: All `:` Commands
  266. | Command | Alias | What it does |
  267. |---|---|---|
  268. | `: <prompt>` | | Send prompt to active agent |
  269. | `:new` | `:n` | Start new conversation |
  270. | `:conversation` | `:c` | Browse/switch conversations (interactive picker) |
  271. | `:conversation -` | | Toggle to previous conversation |
  272. | `:clone` | | Branch current conversation |
  273. | `:rename <name>` | `:rn` | Rename current conversation |
  274. | `:conversation-rename` | | Rename conversation (interactive picker) |
  275. | `:retry` | `:r` | Retry last prompt |
  276. | `:copy` | | Copy last response to clipboard |
  277. | `:dump` | `:d` | Export conversation as JSON |
  278. | `:compact` | | Compact context |
  279. | `:commit` | | AI commit (immediate) |
  280. | `:commit-preview` | | AI commit (review first) |
  281. | `:suggest <desc>` | `:s` | Translate natural language to command |
  282. | `:edit` | `:ed` | Compose prompt in $EDITOR |
  283. | `:sage <prompt>` | `:ask` | Q&A / code understanding agent |
  284. | `:muse <prompt>` | `:plan` | Planning agent |
  285. | `:agent <name>` | `:a` | Switch active agent (interactive picker if no name given) |
  286. | `:model <id>` | `:m` | Set model for this session only |
  287. | `:config-model <id>` | `:cm` | Set default model (persistent) |
  288. | `:reasoning-effort <lvl>` | `:re` | Set reasoning effort for session |
  289. | `:config-reload` | `:cr` | Reset session overrides to global config |
  290. | `:info` | `:i` | Show session info |
  291. | `:sync` | `:workspace-sync` | Index codebase for semantic search |
  292. | `:tools` | `:t` | List available tools |
  293. | `:skill` | | List available skills |
  294. | `:login` | `:provider-login` | Login to a provider |
  295. | `:logout` | | Logout from a provider |
  296. | `:keyboard-shortcuts` | `:kb` | Show keyboard shortcuts |
  297. | `:doctor` | | Run shell environment diagnostics |
  298. ---
  299. ## Command-Line Options
  300. Here's a quick reference of Forge's command-line options:
  301. | Option | Description |
  302. | ----------------------------------- | ------------------------------------------------------------------------ |
  303. | `-p, --prompt <PROMPT>` | Direct prompt to process without entering interactive mode |
  304. | `-e, --event <EVENT>` | Dispatch an event to the workflow in JSON format |
  305. | `--conversation <CONVERSATION>` | Path to a JSON file containing the conversation to execute |
  306. | `--conversation-id <ID>` | Resume or continue an existing conversation by ID |
  307. | `--agent <AGENT>` | Agent ID to use for this session |
  308. | `-C, --directory <DIR>` | Change to this directory before starting |
  309. | `--sandbox <NAME>` | Create an isolated git worktree + branch for safe experimentation |
  310. | `--verbose` | Enable verbose logging output |
  311. | `-h, --help` | Print help information |
  312. | `-V, --version` | Print version |
  313. ### Subcommands
  314. ```bash
  315. # Conversations
  316. forge conversation list # List all saved conversations
  317. forge conversation resume <id> # Resume a conversation in interactive mode
  318. forge conversation new # Create a new conversation ID (prints it)
  319. forge conversation dump <id> # Export conversation as JSON
  320. forge conversation compact <id> # Compact conversation context
  321. forge conversation retry <id> # Retry last message
  322. forge conversation clone <id> # Clone a conversation
  323. forge conversation rename <id> <name> # Rename a conversation
  324. forge conversation delete <id> # Delete a conversation permanently
  325. forge conversation info <id> # Show conversation details
  326. forge conversation stats <id> # Show token usage statistics
  327. forge conversation show <id> # Show last assistant message
  328. # Commits
  329. forge commit # Generate AI commit message and commit
  330. forge commit --preview # Generate commit message only (prints it)
  331. forge commit fix the auth bug # Pass extra context for the commit message
  332. # Shell command suggestion
  333. forge suggest "list files by size" # Translate description to a shell command
  334. # Providers
  335. forge provider login # Add or update provider credentials (interactive)
  336. forge provider logout # Remove provider credentials
  337. forge list provider # List supported providers
  338. # Models & agents
  339. forge list model # List available models
  340. forge list agent # List available agents
  341. # Workspace / semantic search
  342. forge workspace sync # Index current directory for semantic search
  343. forge workspace init # Initialize workspace
  344. forge workspace status # Show indexing status
  345. forge workspace query <text> # Query the semantic index
  346. # MCP servers
  347. forge mcp list # List configured MCP servers
  348. forge mcp import # Add a server from JSON
  349. forge mcp show # Show server configuration
  350. forge mcp remove # Remove a server
  351. forge mcp reload # Reload all servers and rebuild caches
  352. # Other
  353. forge info # Show config, active model, environment
  354. forge list tool --agent <id> # List tools for a specific agent
  355. forge doctor # Run shell environment diagnostics
  356. forge update # Update forge to the latest version
  357. forge setup # Install ZSH plugin (updates .zshrc)
  358. ```
  359. ## Advanced Configuration
  360. ### Provider Configuration
  361. Forge supports multiple AI providers. The recommended way to configure providers is using the interactive login command:
  362. ```bash
  363. forge provider login
  364. ```
  365. This will:
  366. 1. Show you a list of available providers
  367. 2. Guide you through entering the required credentials
  368. #### Managing Provider Credentials
  369. ```bash
  370. # Login to a provider (add or update credentials)
  371. forge provider login
  372. # Remove provider credentials
  373. forge provider logout
  374. # List supported providers
  375. forge provider list
  376. ```
  377. #### Deprecated: Environment Variables
  378. > **⚠️ DEPRECATED**: Using `.env` files for provider configuration is deprecated and will be removed in a future version. Please use `forge provider login` instead.
  379. For backward compatibility, Forge still supports environment variables. On first run, any credentials found in environment variables will be automatically migrated to file-based storage.
  380. <details>
  381. <summary><strong>Legacy Environment Variable Setup (Deprecated)</strong></summary>
  382. <details>
  383. <summary><strong>OpenRouter</strong></summary>
  384. ```bash
  385. # .env
  386. OPENROUTER_API_KEY=<your_openrouter_api_key>
  387. ```
  388. </details>
  389. <details>
  390. <summary><strong>Requesty</strong></summary>
  391. ```bash
  392. # .env
  393. REQUESTY_API_KEY=<your_requesty_api_key>
  394. ```
  395. </details>
  396. <details>
  397. <summary><strong>x-ai</strong></summary>
  398. ```bash
  399. # .env
  400. XAI_API_KEY=<your_xai_api_key>
  401. ```
  402. </details>
  403. <details>
  404. <summary><strong>z.ai</strong></summary>
  405. ```bash
  406. # .env
  407. ZAI_API_KEY=<your_zai_api_key>
  408. # Or for coding plan subscription
  409. ZAI_CODING_API_KEY=<your_zai_coding_api_key>
  410. ```
  411. </details>
  412. <details>
  413. <summary><strong>Cerebras</strong></summary>
  414. ```bash
  415. # .env
  416. CEREBRAS_API_KEY=<your_cerebras_api_key>
  417. ```
  418. </details>
  419. <details>
  420. <summary><strong>Neuralwatt</strong></summary>
  421. ```bash
  422. # .env
  423. NEURALWATT_API_KEY=<your_neuralwatt_api_key>
  424. ```
  425. </details>
  426. <details>
  427. <summary><strong>OrcaRouter</strong></summary>
  428. ```bash
  429. # .env
  430. ORCAROUTER_API_KEY=<your_orcarouter_api_key>
  431. ```
  432. </details>
  433. <details>
  434. <summary><strong>Meta</strong></summary>
  435. ```bash
  436. # .env
  437. META_API_KEY=<your_meta_model_api_key>
  438. ```
  439. ```yaml
  440. # forge.yaml
  441. model: muse-spark-1.1
  442. ```
  443. </details>
  444. <details>
  445. <summary><strong>IO Intelligence</strong></summary>
  446. ```bash
  447. # .env
  448. IO_INTELLIGENCE_API_KEY=<your_io_intelligence_api_key>
  449. ```
  450. ```yaml
  451. # forge.yaml
  452. model: meta-llama/Llama-3.3-70B-Instruct
  453. ```
  454. </details>
  455. <details>
  456. <summary><strong>OpenAI</strong></summary>
  457. ```bash
  458. # .env
  459. OPENAI_API_KEY=<your_openai_api_key>
  460. ```
  461. ```yaml
  462. # forge.yaml
  463. model: o3-mini-high
  464. ```
  465. </details>
  466. <details>
  467. <summary><strong>Anthropic</strong></summary>
  468. ```bash
  469. # .env
  470. ANTHROPIC_API_KEY=<your_anthropic_api_key>
  471. ```
  472. ```yaml
  473. # forge.yaml
  474. model: claude-3.7-sonnet
  475. ```
  476. </details>
  477. <details>
  478. <summary><strong>Google Vertex AI</strong></summary>
  479. **Setup Instructions:**
  480. 1. **Install Google Cloud CLI** and authenticate:
  481. ```bash
  482. gcloud auth login
  483. gcloud config set project YOUR_PROJECT_ID
  484. ```
  485. 2. **Get your authentication token**:
  486. ```bash
  487. gcloud auth print-access-token
  488. ```
  489. 3. **Use the token when logging in via Forge**:
  490. ```bash
  491. forge provider login
  492. # Select Google Vertex AI and enter your credentials
  493. ```
  494. **Legacy `.env` setup:**
  495. ```bash
  496. # .env
  497. PROJECT_ID=<your_project_id>
  498. LOCATION=<your_location>
  499. VERTEX_AI_AUTH_TOKEN=<your_auth_token>
  500. ```
  501. ```yaml
  502. # forge.yaml
  503. model: google/gemini-2.5-pro
  504. ```
  505. **Available Models:**
  506. - Claude models: `claude-sonnet-4@20250514`
  507. - Gemini models: `gemini-2.5-pro`, `gemini-2.0-flash`
  508. Use the `/model` command in Forge CLI to see all available models.
  509. </details>
  510. <details>
  511. <summary><strong>OpenAI-Compatible Providers</strong></summary>
  512. ```bash
  513. # .env
  514. OPENAI_API_KEY=<your_provider_api_key>
  515. OPENAI_URL=<your_provider_url>
  516. ```
  517. ```yaml
  518. # forge.yaml
  519. model: <provider-specific-model>
  520. ```
  521. </details>
  522. <details>
  523. <summary><strong>Groq</strong></summary>
  524. ```bash
  525. # .env
  526. OPENAI_API_KEY=<your_groq_api_key>
  527. OPENAI_URL=https://api.groq.com/openai/v1
  528. ```
  529. ```yaml
  530. # forge.yaml
  531. model: deepseek-r1-distill-llama-70b
  532. ```
  533. </details>
  534. <details>
  535. <summary><strong>Amazon Bedrock</strong></summary>
  536. To use Amazon Bedrock models with Forge, you'll need to first set up the [Bedrock Access Gateway](https://github.com/aws-samples/bedrock-access-gateway):
  537. 1. **Set up Bedrock Access Gateway**:
  538. - Follow the deployment steps in the [Bedrock Access Gateway repo](https://github.com/aws-samples/bedrock-access-gateway)
  539. - Create your own API key in Secrets Manager
  540. - Deploy the CloudFormation stack
  541. - Note your API Base URL from the CloudFormation outputs
  542. 2. **Configure in Forge**:
  543. ```bash
  544. forge provider login
  545. # Select OpenAI-compatible provider and enter your Bedrock Gateway details
  546. ```
  547. **Legacy `.env` setup:**
  548. ```bash
  549. # .env
  550. OPENAI_API_KEY=<your_bedrock_gateway_api_key>
  551. OPENAI_URL=<your_bedrock_gateway_base_url>
  552. ```
  553. ```yaml
  554. # forge.yaml
  555. model: anthropic.claude-3-opus
  556. ```
  557. </details>
  558. <details>
  559. <summary><strong>ForgeCode Services</strong></summary>
  560. ```bash
  561. # .env
  562. FORGE_API_KEY=<your_forge_api_key>
  563. ```
  564. ```yaml
  565. # forge.yaml
  566. model: claude-3.7-sonnet
  567. ```
  568. </details>
  569. </details>
  570. ---
  571. ### forge.yaml Configuration Options
  572. ### Environment Variables
  573. Forge supports several environment variables for advanced configuration and fine-tuning. These can be set in your `.env` file or system environment.
  574. <details>
  575. <summary><strong>Retry Configuration</strong></summary>
  576. Control how Forge handles retry logic for failed requests:
  577. ```bash
  578. # .env
  579. FORGE_RETRY_INITIAL_BACKOFF_MS=1000 # Initial backoff time in milliseconds (default: 1000)
  580. FORGE_RETRY_BACKOFF_FACTOR=2 # Multiplier for backoff time (default: 2)
  581. FORGE_RETRY_MAX_ATTEMPTS=3 # Maximum retry attempts (default: 3)
  582. FORGE_SUPPRESS_RETRY_ERRORS=false # Suppress retry error messages (default: false)
  583. FORGE_RETRY_STATUS_CODES=429,500,502 # HTTP status codes to retry (default: 429,500,502,503,504)
  584. ```
  585. </details>
  586. <details>
  587. <summary><strong>HTTP Configuration</strong></summary>
  588. Fine-tune HTTP client behavior for API requests:
  589. ```bash
  590. # .env
  591. FORGE_HTTP_CONNECT_TIMEOUT=30 # Connection timeout in seconds (default: 30)
  592. FORGE_HTTP_READ_TIMEOUT=900 # Read timeout in seconds (default: 900)
  593. FORGE_HTTP_POOL_IDLE_TIMEOUT=90 # Pool idle timeout in seconds (default: 90)
  594. FORGE_HTTP_POOL_MAX_IDLE_PER_HOST=5 # Max idle connections per host (default: 5)
  595. FORGE_HTTP_MAX_REDIRECTS=10 # Maximum redirects to follow (default: 10)
  596. FORGE_HTTP_USE_HICKORY=false # Use Hickory DNS resolver (default: false)
  597. FORGE_HTTP_TLS_BACKEND=default # TLS backend: "default" or "rustls" (default: "default")
  598. FORGE_HTTP_MIN_TLS_VERSION=1.2 # Minimum TLS version: "1.0", "1.1", "1.2", "1.3"
  599. FORGE_HTTP_MAX_TLS_VERSION=1.3 # Maximum TLS version: "1.0", "1.1", "1.2", "1.3"
  600. FORGE_HTTP_ADAPTIVE_WINDOW=true # Enable HTTP/2 adaptive window (default: true)
  601. FORGE_HTTP_KEEP_ALIVE_INTERVAL=60 # Keep-alive interval in seconds (default: 60, use "none"/"disabled" to disable)
  602. FORGE_HTTP_KEEP_ALIVE_TIMEOUT=10 # Keep-alive timeout in seconds (default: 10)
  603. FORGE_HTTP_KEEP_ALIVE_WHILE_IDLE=true # Keep-alive while idle (default: true)
  604. FORGE_HTTP_ACCEPT_INVALID_CERTS=false # Accept invalid certificates (default: false) - USE WITH CAUTION
  605. FORGE_HTTP_ROOT_CERT_PATHS=/path/to/cert1.pem,/path/to/cert2.crt # Paths to root certificate files (PEM, CRT, CER format), multiple paths separated by commas
  606. ```
  607. > **⚠️ Security Warning**: Setting `FORGE_HTTP_ACCEPT_INVALID_CERTS=true` disables SSL/TLS certificate verification, which can expose you to man-in-the-middle attacks. Only use this in development environments or when you fully trust the network and endpoints.
  608. </details>
  609. <details>
  610. <summary><strong>API Configuration</strong></summary>
  611. Override default API endpoints and provider/model settings:
  612. ```bash
  613. # .env
  614. FORGE_API_URL=https://api.forgecode.dev # Custom Forge API URL (default: https://api.forgecode.dev)
  615. FORGE_WORKSPACE_SERVER_URL=http://localhost:8080 # URL for the indexing server (default: https://api.forgecode.dev/)
  616. ```
  617. </details>
  618. <details>
  619. <summary><strong>Tool Configuration</strong></summary>
  620. Configuring the tool calls settings:
  621. ```bash
  622. # .env
  623. FORGE_TOOL_TIMEOUT=300 # Maximum execution time in seconds for a tool before it is terminated to prevent hanging the session. (default: 300)
  624. FORGE_MAX_IMAGE_SIZE=10485760 # Maximum image file size in bytes for read_image operations (default: 10485760 - 10 MB)
  625. FORGE_DUMP_AUTO_OPEN=false # Automatically open dump files in browser (default: false)
  626. FORGE_DEBUG_REQUESTS=/path/to/debug/requests.json # Write debug HTTP request files to specified path (supports absolute and relative paths)
  627. ```
  628. </details>
  629. <details>
  630. <summary><strong>ZSH Plugin Configuration</strong></summary>
  631. Configure the ZSH plugin behavior:
  632. ```bash
  633. # .env
  634. FORGE_BIN=forge # Command to use for forge operations (default: "forge")
  635. ```
  636. The `FORGE_BIN` environment variable allows you to customize the command used by the ZSH plugin when transforming `:` prefixed commands. If not set, it defaults to `"forge"`.
  637. </details>
  638. <details>
  639. <summary><strong>Display Configuration</strong></summary>
  640. Configure display options for the Forge UI and ZSH theme:
  641. ```bash
  642. # .env
  643. FORGE_CURRENCY_SYMBOL="$" # Currency symbol for cost display in ZSH theme (default: "$")
  644. FORGE_CURRENCY_CONVERSION_RATE=1.0 # Conversion rate for currency display (default: 1.0)
  645. NERD_FONT=1 # Enable Nerd Font icons in ZSH theme (default: auto-detected, set to "1" or "true" to enable, "0" or "false" to disable)
  646. USE_NERD_FONT=1 # Alternative variable for enabling Nerd Font icons (same behavior as NERD_FONT)
  647. ```
  648. The `FORGE_CURRENCY_SYMBOL` and `FORGE_CURRENCY_CONVERSION_RATE` variables control how costs are displayed in the ZSH theme right prompt. Use these to customize the currency display for your region or preferred currency.
  649. </details>
  650. <details>
  651. <summary><strong>System Configuration</strong></summary>
  652. System-level environment variables (usually set automatically):
  653. ```bash
  654. # .env
  655. FORGE_CONFIG=/custom/config/dir # Base directory for all Forge config files (default: ~/.forge)
  656. FORGE_MAX_SEARCH_RESULT_BYTES=10240 # Maximum bytes for search results (default: 10240 - 10 KB)
  657. FORGE_HISTORY_FILE=/path/to/history # Custom path for Forge history file (default: uses system default location)
  658. FORGE_BANNER="Your custom banner text" # Custom banner text to display on startup (default: Forge ASCII art)
  659. FORGE_MAX_CONVERSATIONS=100 # Maximum number of conversations to show in list (default: 100)
  660. FORGE_MAX_LINE_LENGTH=2000 # Maximum characters per line for file read operations (default: 2000)
  661. FORGE_STDOUT_MAX_LINE_LENGTH=2000 # Maximum characters per line for shell output (default: 2000)
  662. SHELL=/bin/zsh # Shell to use for command execution (Unix/Linux/macOS)
  663. COMSPEC=cmd.exe # Command processor to use (Windows)
  664. ```
  665. </details>
  666. <details>
  667. <summary><strong>Semantic Search Configuration</strong></summary>
  668. Configure semantic search behavior for code understanding:
  669. ```bash
  670. # .env
  671. FORGE_SEM_SEARCH_LIMIT=200 # Maximum number of results to return from initial vector search (default: 200)
  672. FORGE_SEM_SEARCH_TOP_K=20 # Top-k parameter for relevance filtering during semantic search (default: 20)
  673. ```
  674. </details>
  675. <details>
  676. <summary><strong>Logging Configuration</strong></summary>
  677. Configure logging verbosity and output:
  678. ```bash
  679. # .env
  680. FORGE_LOG=forge=info # Log filter level (default: forge=debug when tracking disabled, forge=info when tracking enabled)
  681. ```
  682. The `FORGE_LOG` variable controls the logging level for Forge's internal operations using the standard tracing filter syntax. Common values:
  683. - `forge=error` - Only errors
  684. - `forge=warn` - Warnings and errors
  685. - `forge=info` - Informational messages (default when tracking enabled)
  686. - `forge=debug` - Debug information (default when tracking disabled)
  687. - `forge=trace` - Detailed tracing
  688. </details>
  689. <details>
  690. <summary><strong>Tracking Configuration</strong></summary>
  691. Control tracking of user-identifying metadata in telemetry events:
  692. ```bash
  693. # .env
  694. FORGE_TRACKER=false # Disable tracking enrichment metadata (default: true)
  695. ```
  696. The `FORGE_TRACKER` variable controls whether tracking enrichment metadata is included in telemetry events.
  697. </details>
  698. The `forge.yaml` file supports several advanced configuration options that let you customize Forge's behavior.
  699. <details>
  700. <summary><strong>Custom Rules</strong></summary>
  701. Add your own guidelines that all agents should follow when generating responses.
  702. ```yaml
  703. # forge.yaml
  704. custom_rules: |
  705. 1. Always add comprehensive error handling to any code you write.
  706. 2. Include unit tests for all new functions.
  707. 3. Follow our team's naming convention: camelCase for variables, PascalCase for classes.
  708. ```
  709. </details>
  710. <details>
  711. <summary><strong>Commands</strong></summary>
  712. Define custom commands as shortcuts for repetitive prompts:
  713. ```yaml
  714. # forge.yaml
  715. commands:
  716. - name: "refactor"
  717. description: "Refactor selected code"
  718. prompt: "Please refactor this code to improve readability and performance"
  719. ```
  720. </details>
  721. <details>
  722. <summary><strong>Model</strong></summary>
  723. Specify the default AI model to use for all agents in the workflow.
  724. ```yaml
  725. # forge.yaml
  726. model: "claude-3.7-sonnet"
  727. ```
  728. </details>
  729. <details>
  730. <summary><strong>Max Walker Depth</strong></summary>
  731. Control how deeply Forge traverses your project directory structure when gathering context.
  732. ```yaml
  733. # forge.yaml
  734. max_walker_depth: 3 # Limit directory traversal to 3 levels deep
  735. ```
  736. </details>
  737. <details>
  738. <summary><strong>Temperature</strong></summary>
  739. Adjust the creativity and randomness in AI responses. Lower values (0.0-0.3) produce more focused, deterministic outputs, while higher values (0.7-2.0) generate more diverse and creative results.
  740. ```yaml
  741. # forge.yaml
  742. temperature: 0.7 # Balanced creativity and focus
  743. ```
  744. </details>
  745. <details>
  746. <summary><strong>Tool Max Failure Limit</strong></summary>
  747. Control how many times a tool can fail before Forge forces completion to prevent infinite retry loops. This helps avoid situations where an agent gets stuck repeatedly trying the same failing operation.
  748. ```yaml
  749. # forge.yaml
  750. max_tool_failure_per_turn: 3 # Allow up to 3 failures per tool before forcing completion
  751. ```
  752. Set to a higher value if you want more retry attempts, or lower if you want faster failure detection.
  753. </details>
  754. <details>
  755. <summary><strong>Max Requests Per Turn</strong></summary>
  756. Limit the maximum number of requests an agent can make in a single conversation turn. This prevents runaway conversations and helps control API usage and costs.
  757. ```yaml
  758. # forge.yaml
  759. max_requests_per_turn: 50 # Allow up to 50 requests per turn
  760. ```
  761. When this limit is reached, Forge will:
  762. - Ask you if you wish to continue
  763. - If you respond with 'Yes', it will continue the conversation
  764. - If you respond with 'No', it will end the conversation
  765. </details>
  766. ---
  767. <details>
  768. <summary><strong>Model Context Protocol (MCP)</strong></summary>
  769. The MCP feature allows AI agents to communicate with external tools and services. This implementation follows Anthropic's [Model Context Protocol](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp) design.
  770. ### MCP Configuration
  771. Configure MCP servers using the CLI:
  772. ```bash
  773. # List all MCP servers
  774. forge mcp list
  775. # Import a server from JSON
  776. forge mcp import
  777. # Show server configuration details
  778. forge mcp show
  779. # Remove a server
  780. forge mcp remove
  781. # Reload servers and rebuild caches
  782. forge mcp reload
  783. ```
  784. Or manually create a `.mcp.json` file with the following structure:
  785. ```json
  786. {
  787. "mcpServers": {
  788. "server_name": {
  789. "command": "command_to_execute",
  790. "args": ["arg1", "arg2"],
  791. "env": { "ENV_VAR": "value" }
  792. },
  793. "another_server": {
  794. "url": "http://localhost:3000/events"
  795. }
  796. }
  797. }
  798. ```
  799. MCP configurations are read from two locations (project-local takes precedence):
  800. 1. **Project-local:** `.mcp.json` in your project directory
  801. 2. **Global:** `~/forge/.mcp.json`
  802. ### Example Use Cases
  803. MCP can be used for various integrations:
  804. - Web browser automation
  805. - External API interactions
  806. - Tool integration
  807. - Custom service connections
  808. ### Usage in Multi-Agent Workflows
  809. MCP tools can be used as part of multi-agent workflows, allowing specialized agents to interact with external systems as part of a collaborative problem-solving approach.
  810. </details>
  811. ---
  812. ## Documentation
  813. For comprehensive documentation on all features and capabilities, please visit the [documentation site](https://github.com/tailcallhq/forgecode/tree/main/docs).
  814. ---
  815. ## Installation
  816. ```bash
  817. # YOLO
  818. curl -fsSL https://forgecode.dev/cli | sh
  819. # Package managers
  820. nix run github:tailcallhq/forgecode # for latest dev branch
  821. ```
  822. ---
  823. ## Community
  824. Join our vibrant Discord community to connect with other Forge users and contributors, get help with your projects, share ideas, and provide feedback!
  825. [![Discord](https://img.shields.io/discord/1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https://discord.gg/kRZBPpkgwq)
  826. ---
  827. ## Support Us
  828. Your support drives Forge's continued evolution! By starring our GitHub repository, you:
  829. - Help others discover this powerful tool 🔍
  830. - Motivate our development team 💪
  831. - Enable us to prioritize new features 🛠️
  832. - Strengthen our open-source community 🌱

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.