The Forest

The Forest is a platform for discovering, publishing, and installing AI plugins from GitHub.

It is designed to help users find plugins that work with multiple AI ecosystems, including Claude, Codex, Gemini, GLM, and Qwen. Each listing should clearly show:

• what the plugin does
• which models it supports
• where the GitHub source lives
• how to install it locally with a command

This repository now contains a runnable MVP with:

• a web UI
• English and Chinese interface switching on the public site
• a local registry API
• a file-backed data store
• a Postgres-ready repository layer
• a working forest CLI
• a Cloudflare Worker deployment path with Assets, R2, and KV

Design package

The repository now also includes implementation design docs for the next stage:

• docs/system-design.md: product architecture, user roles, domain model, and service boundaries
• docs/openapi.yaml: API contract for web app, maintainer console, and CLI
• docs/schema.sql: initial Postgres schema for users, plugins, versions, submissions, and installs
• docs/cli-design.md: command surface, config layout, install flow, and adapter design
• docs/forest.plugin.example.json: example plugin manifest format for GitHub repositories

MVP goals

The first version of The Forest should support:

• plugin discovery with search and filters
• a compatibility matrix for AI models
• local install commands such as forest add <plugin> --target <model>
• GitHub-based plugin listings
• user registration for plugin maintainers and community users

Included in this MVP

• index.html: web app shell
• styles.css: visual design, layout, and responsive behavior
• app.js: frontend logic powered by the live API
• server.js: Node HTTP server for static files and registry endpoints
• worker.mjs: Cloudflare Worker entry for API routes, static assets, KV storage, and R2 uploads
• wrangler.toml: Cloudflare deployment config
• bin/forest.js: local CLI for search, auth, install, list, remove, validate, publish, and GitHub-aware sync checks
• forest: repo-local launcher for the CLI command
• data/registry.json: local JSON data store for site info, users, plugins, tokens, and submissions
• lib/store.js: data persistence helpers
• lib/registry.js: registry domain logic
• lib/repositories/: switchable storage layer for JSON now and Postgres next
• lib/http.js: shared HTTP response helpers
• lib/target-adapters.js: target-specific local config writers for Codex, Claude Desktop, and others

Product direction

The Forest can grow into a real platform with these core areas:

1. Registry Store plugin metadata, GitHub links, versions, categories, supported models, and install instructions.

2. Accounts Let users register, save favorite plugins, and manage published listings.

3. Maintainer tools Allow plugin authors to submit plugins, verify ownership, and update compatibility or release notes.

4. CLI Provide a forest command that searches, installs, updates, and removes plugins locally.

5. Trust layer Add verification, community ratings, install counts, and security checks.

Current feature set

• plugin search and filter from the live API
• plugin detail panel with versions, permissions, and install targets
• account registration and sign-in
• plugin submission flow
• local CLI auth, search, info, install, list, update, remove, doctor, validate, and publish
• CLI-first publishing from the current project directory through plugin-claim.json + auto-zipped bundles
• GitHub-aware CLI import for publish, plus remote repo validation and optional registry sync through validate
• contact and donation sidebar data served from the backend

Real local config writes

The CLI now writes target-specific config files instead of only saving local install state:

• codex: ~/.codex/config.toml
• claude-desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• command-style targets such as claude-code, gemini-cli, glm, and qwen: target-specific plugins.json files

For safe testing, you can redirect target writes away from your real home directory:

FOREST_TARGET_HOME=/tmp/the-forest-targets npm run dev

And for CLI commands:

FOREST_HOME=/tmp/the-forest-cli FOREST_TARGET_HOME=/tmp/the-forest-targets node bin/forest.js add github/repo-context --target codex

Run locally

Start the app:

npm run dev

Then open http://127.0.0.1:3000.

Optional runtime settings:

FOREST_STORE_DRIVER=json npm run dev
DATABASE_URL=postgres://user:pass@host:5432/the_forest FOREST_STORE_DRIVER=postgres npm run dev
DATABASE_URL=postgres://user:pass@host:5432/the_forest FOREST_PG_SCHEMA=the_forest npm run db:migrate
DATABASE_URL=postgres://user:pass@host:5432/the_forest FOREST_PG_SCHEMA=the_forest npm run db:seed

Health endpoint:

curl http://127.0.0.1:3000/v1/health

Deploy with Docker

If you do not want to deploy on Cloudflare, the fastest path is Docker Compose.

Files included:

• Dockerfile
• docker-compose.yml
• docker-compose.prod.yml
• .dockerignore
• .env.production.example

This setup runs:

• The Forest app on port 3000
• PostgreSQL 16 in a companion container
• automatic schema migration on app startup
• persistent Docker volumes for Postgres data and uploaded images

Start it:

docker compose up --build

Then open:

• http://127.0.0.1:3000
• http://127.0.0.1:3000/admin

Default container environment:

• database: the_forest
• user: forest
• password: forestpass
• schema: the_forest

Stop it:

docker compose down

Stop it and remove volumes:

docker compose down -v

Production-style compose:

cp .env.production.example .env.production
docker compose -f docker-compose.prod.yml up -d --build

Stop production compose:

docker compose -f docker-compose.prod.yml down

Node version

Cloudflare deployment tasks in this repository use wrangler@4, which requires Node.js >= 20.

This repo includes .nvmrc, so if you use nvm:

nvm install 20
nvm use

Deploy on Cloudflare

This project can now run on Cloudflare as a Worker-based deployment:

• static files are served through the ASSETS binding
• uploaded QR images are stored in R2
• registry data is stored in Cloudflare KV

Before deploying:

1. Create an R2 bucket, for example the-forest-uploads
2. Create a KV namespace and bind it as REGISTRY_KV
3. Update wrangler.toml with your real KV namespace id and bucket name if needed
4. Use Node.js >= 20 for Wrangler commands and Cloudflare deploy tasks

Recommended Worker vars:

• FOREST_STORE_DRIVER=kv

Useful commands:

npm run cf:dev
npm run cf:deploy
npm run cf:migrate-uploads -- --dry-run

If you prefer not to install Wrangler globally, use:

npx wrangler dev
npx wrangler deploy

Notes:

• the Worker auto-seeds KV from data/registry.json on first access
• local filesystem uploads are replaced by R2 at /uploads/...
• Cloudflare KV in this project is a single-document registry store, which is simple to deploy but is still best suited to MVP and light admin traffic
• root assets are filtered through .assetsignore so only the web app files are published as static assets
• full deployment checklist: docs/cloudflare-deploy.md
• local verification in this workspace reached the Wrangler boundary: [email protected] requires Node.js >= 20, while the current shell is Node 18.17.1

CLI examples

Use the forest command

Inside this repository you can run:

./forest --help

For most users, install the published package globally:

npm install -g @evanszhang/forest

Then you can use:

forest --help
forest search github
forest init-claim
forest publish

By default, the published CLI connects to:

https://the-forest.alphejangs.workers.dev

If you need to point the CLI at a local registry during development, override it with FOREST_REGISTRY_URL.

If you are developing inside this repository and want a linked local command:

npm link

Publish to npm

This repository is now configured as an npm-publishable CLI package:

• package name: @evanszhang/forest
• installed command: forest
• publish access: public

Before publishing:

npm login
npm pack --dry-run
npm publish --access public

Package metadata:

• package: @evanszhang/forest
• command: forest
• license: MIT
• repository: https://github.com/AlpherJang/the-forest

Search and inspect:

forest search github
forest info github/repo-context

Register and log in:

forest auth register --email [email protected] --password "your-password" --name "Your Name"
forest auth login --email [email protected] --password "your-password"

Install and list:

forest add github/repo-context --target codex --env GITHUB_TOKEN=example-token
forest list
forest doctor codex

Submit a plugin:

forest init-claim
forest validate ./plugin-claim.json
forest publish

Validate a local manifest or a remote GitHub repo:

forest validate ./plugin-claim.json
forest validate ./forest.plugin.json
forest validate --repo https://github.com/owner/plugin-repo
forest validate --repo https://github.com/owner/plugin-repo --plugin owner/plugin-repo --sync

Example plugin-claim.json:

{
  "schemaVersion": "1.0",
  "id": "owner/plugin-name",
  "name": "My Plugin",
  "description": "Describe what your plugin does.",
  "repositoryUrl": "https://github.com/owner/plugin-name",
  "version": "0.1.0",
  "entrypoint": "dist/index.js",
  "categories": ["development"],
  "models": ["codex", "claude"]
}

When you run forest publish inside the plugin directory, the CLI will:

1. read plugin-claim.json
2. validate the publish metadata
3. zip the current directory
4. upload the bundle to the registry
5. create the submission automatically

Important note

The project now supports both JSON-backed and Postgres-backed runtime modes. JSON is still the easiest zero-setup default, while Postgres is intended for the real multi-user path. If you share a database with other apps, set FOREST_PG_SCHEMA so The Forest stays isolated inside its own schema.