🤖 Ramenos CLI

A lightning-fast, zero-dependency CLI to share and install AI multi-agent orchestration configurations directly from GitHub into your local workspace.

Designed for modern AI coding assistants like OpenCode, Gemini CLI, Claude Code, and Codex. Bootstrapping a focused multi-agent AI team is one command away.

✨ Features

🚀 Zero Dependencies: Built with native Node.js. Incredibly fast execution.
🔗 Smart Caching: Uses local caching to safely manage agent files without cluttering your project.
🐙 Flexible Git Support: Supports GitHub shorthand, raw HTTPS, SSH, and deep folder trees.
🎯 Multi-Framework: Install to .opencode/agents/, .gemini/agents/, .claude/agents/, .codex/agents/, or any custom structure — all from a single command.
📋 Presets: Choose between new (full startup pipeline) and continue (task delegation for existing projects).
🧩 Header + Prompt Architecture: Framework-specific headers are combined with shared prompts at install time — no duplication.
🗑️ Clean Uninstall: Remove agents with ramenos del using the same options.

🚀 Quick Start

No global installation is required! Run it directly via npx inside your project directory:

# Add agents for an existing project (defaults: opencode + continue preset)
npx ramenos add maxylev/ramenos

# Add agents for all supported frameworks
npx ramenos add maxylev/ramenos -a opencode gemini claude codex

# Add agents for a new startup project
npx ramenos add maxylev/ramenos -p new

# Add agents globally
npx ramenos add maxylev/ramenos --global

To remove agents later:

# Remove the same agents you installed
npx ramenos del maxylev/ramenos

# Remove from all frameworks
npx ramenos del maxylev/ramenos -a opencode gemini claude codex

# Remove from global directory
npx ramenos del maxylev/ramenos -g

📖 Usage Guide

Commands

Command	Description
`add <repository>`	Install agent files into your project
`del <repository>`	Remove previously installed agent files

Options

Usage: ramenos <add|del> <repository> [options]

Options:
  -g, --global              Target the framework's global agent directory
  -a, --agent <agents...>   Target frameworks. Defaults to 'opencode'.
                            Supported: opencode, gemini, claude, codex, or any custom name.
  -p, --preset <preset>     Prompt preset: 'new' or 'continue'. Defaults to 'continue'.
                            new      — Full startup pipeline (ideation → deployment)
                            continue — Task delegation for existing projects
  --copy                    Copy files instead of symlinking (legacy mode only)
  -y, --yes                 Skip all confirmation prompts
  -h, --help                Display help message

Examples

Install for all supported frameworks at once:

npx ramenos add maxylev/ramenos -a opencode gemini claude codex

Start a new startup project from scratch:

npx ramenos add maxylev/ramenos -p new

Install for Gemini CLI with the continue preset:

npx ramenos add maxylev/ramenos -a gemini -p continue

Remove agents from a specific framework:

npx ramenos del maxylev/ramenos -a gemini

Remove all agents and clean up:

npx ramenos del maxylev/ramenos -a opencode gemini claude codex

CI/CD or Automated Scripting:

npx ramenos add maxylev/ramenos --yes -a opencode gemini claude codex

🎯 Target Frameworks

Ramenos knows the correct directory structure for popular AI tools:

Framework	Local Path	Global Path (`-g`)
`opencode`	`.opencode/agents/`	`~/.config/opencode/agents/`
`gemini`	`.gemini/agents/`	`~/.gemini/agents/`
`claude`	`.claude/agents/`	`~/.claude/agents/`
`codex`	`.codex/agents/`	`~/.codex/agents/`
any custom	`.<name>/agents/`	`~/.config/<name>/agents/`

📋 Presets

Presets control the system prompt that gets combined with the framework-specific header at install time.

`continue` (default)

For existing projects that need a leader/developer hierarchy. The developer reports to the leader until the user's assigned task is complete. No planning files, no phases — just task delegation and verification.

`new`

For starting from scratch — a full startup pipeline with phases: Ideation → Validation → Architecture → Planning → Implementation → Testing → Deployment. Uses IMPLEMENTATION_PLAN.md for state tracking.

🔗 Supported Repository Formats

Ramenos looks for an agents/ folder by default in the root of the repository, but supports deep links if you want to pull a specific sub-folder.

1. GitHub Shorthand:

npx ramenos add my-labs/my-awesome-agents

2. Direct Sub-folder Links:

npx ramenos add https://github.com/ai-labs/my-agents/tree/main/agents/orchestration

3. SSH Formats:

npx ramenos add git@github.com:my-company/internal-agents.git

🛠️ Creating Your Own Agent Repo

Want to share your own agents via ramenos? Use the structured format with separate headers and prompts:

my-awesome-agents/
├── README.md
└── agents/
    ├── headers/
    │   ├── opencode/
    │   │   ├── leader.md      # Frontmatter for opencode
    │   │   ├── developer.md
    │   │   └── researcher.md  # Web-only research subagent
    │   ├── gemini/
    │   │   ├── leader.md      # Frontmatter for gemini
    │   │   ├── developer.md
    │   │   └── researcher.md
    │   ├── claude/
    │   │   ├── leader.md      # Frontmatter for claude
    │   │   ├── developer.md
    │   │   └── researcher.md
    │   └── codex/
    │       ├── leader.toml    # Base Codex custom-agent config
    │       ├── developer.toml
    │       └── researcher.toml
    └── prompts/
        ├── new/
        │   ├── leader.md      # Prompt body for "new" preset
        │   ├── developer.md
        │   └── researcher.md
        └── continue/
            ├── leader.md      # Prompt body for "continue" preset
            ├── developer.md
            └── researcher.md

Then anyone can install your setup using: npx ramenos add your-username/my-awesome-agents

Header Files

Header files contain only framework-specific configuration. OpenCode, Gemini, and Claude use YAML frontmatter with --- delimiters. Codex uses a TOML base configuration; Ramenos adds the selected prompt as the required top-level developer_instructions field.

opencode (headers/opencode/leader.md):

---
description: My leader agent description
mode: primary
model: router/leader
temperature: 0.1
---

gemini (headers/gemini/leader.md):

---
name: leader
description: My leader agent description
tools:
  - read_file
  - write_file
  - grep_search
---

claude (headers/claude/leader.md):

---
name: leader
description: My leader agent description
tools: Agent(developer), Read, Glob, Grep, Bash
model: inherit
permissionMode: auto
---

codex (headers/codex/developer.toml):

name = "developer"
description = "Implementation-focused engineer for targeted code changes and tests."
nickname_candidates = ["Builder", "Forge"]
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

Do not add developer_instructions to a Codex header. Ramenos generates it from prompts/<preset>/<agent>.md. Codex custom agents inherit omitted configuration from the parent session, so model, reasoning, sandbox, MCP, and skill settings can be left out when inheritance is preferred.

Prompt Files

Prompt files contain only the markdown body (no frontmatter). They are shared across all frameworks:

You are the Leader agent. Your job is to orchestrate the development workflow...

**RULES:**

- Rule 1
- Rule 2

Researcher Subagent

Ramenos includes a focused researcher subagent for internet work. The leader and developer prompts delegate live web searches, documentation checks, and market facts to the researcher instead of filling their own context with web pages. Framework headers limit the researcher to read-only or web-focused capabilities where supported.

The researcher prompt requires visited-source verification, concise citations, dates for time-sensitive claims, and clear disclosure when evidence cannot be verified.

For Codex, custom agents are spawned agents rather than primary personas. If you spawn leader and expect it to delegate to developer or researcher, configure agents.max_depth = 2 in Codex. Keep the default depth of 1 when the root session delegates directly to the developer and researcher agents.

🏗️ How It Works

`add`

Fetch: The repository is cloned (or updated) into ~/.ramenos/cache/.
Detect: If the source has headers/ and prompts/ subdirectories, structured mode is used.
Combine: For each target framework, matching header and prompt files are combined. Markdown/YAML targets produce .md files; Codex TOML headers produce .toml files with generated developer_instructions.
Install: Final agent files are written to the framework's project or global agent directory.

`del`

Fetch: The repository is fetched (same as add) to determine which files were installed.
Remove: For each target framework, matching agent files are deleted from its selected project or global agent directory.
Cleanup: If the agents directory is empty after removal, it is deleted automatically.

🧠 Advanced: OpenCode & 9router Setup (for custom model)

For users setting up an advanced local agent workflow with fallback models and delegated web research, follow these steps to integrate OpenCode, 9router, and the searchfetch MCP server.

1. Model Routing with 9router

Run the following command to install and start the 9router:

npm install -g 9router
9router

Configure 9router via the UI at http://localhost:20128 to create model combos with fallback support (e.g., configuring leader and developer endpoints).

2. OpenCode Configuration

Update your opencode.json file to point to your local 9router instance:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "router": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "router",
      "options": {
        "baseURL": "http://localhost:20128/v1"
      },
      "models": {
        "leader": {
          "name": "leader"
        },
        "developer": {
          "name": "developer"
        },
        "researcher": {
          "name": "researcher"
        }
      }
    }
  }
}

Configure the researcher route to use a lower-cost model, then set model: router/researcher in agents/headers/opencode/researcher.md if you want installed researcher agents to use that route.

3. Web Research Subagent (MCP)

Equip only the hidden researcher subagent with web search and website-fetching capability. The leader and developer agent files deny direct searchfetch access and instruct agents to delegate current internet facts to @researcher.

Add the MCP servers to opencode.json; access is controlled per agent by the installed agent permissions.

MCP searchfetch:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "searchfetch": {
      "type": "local",
      "command": ["npx", "-y", "searchfetch"],
      "enabled": true
    }
  }
}

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
agents		agents
bin		bin
src		src
test		test
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🤖 Ramenos CLI

📑 Table of Contents

✨ Features

🚀 Quick Start

📖 Usage Guide

Commands

Options

Examples

🎯 Target Frameworks

📋 Presets

`continue` (default)

`new`

🔗 Supported Repository Formats

🛠️ Creating Your Own Agent Repo

Header Files

Prompt Files

Researcher Subagent

🏗️ How It Works

`add`

`del`

🧠 Advanced: OpenCode & 9router Setup (for custom model)

1. Model Routing with 9router

2. OpenCode Configuration

3. Web Research Subagent (MCP)

About

Uh oh!

Releases 12

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

🤖 Ramenos CLI

📑 Table of Contents

✨ Features

🚀 Quick Start

📖 Usage Guide

Commands

Options

Examples

🎯 Target Frameworks

📋 Presets

continue (default)

new

🔗 Supported Repository Formats

🛠️ Creating Your Own Agent Repo

Header Files

Prompt Files

Researcher Subagent

🏗️ How It Works

add

del

🧠 Advanced: OpenCode & 9router Setup (for custom model)

1. Model Routing with 9router

2. OpenCode Configuration

3. Web Research Subagent (MCP)

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`continue` (default)

`new`

`add`

`del`

Packages