rays-core 1.5.4

RAYS-CORE: AI-powered codebase analysis and editing assistant

RAYS-CORE

Open-source AI coding assistant for real repositories.
Index. Analyze. Plan. Edit. Ship.

---

Preview

Add your hero screenshot/GIF below (the big one at the top like the OpenCode page):

![RAYS-CORE Hero](docs/images/rays-hero.png)

Example layout with short supporting text:

<p align="center">
  <img src="docs/images/rays-hero.png" alt="RAYS-CORE hero screenshot" width="95%" />
</p>
<p align="center"><em>RAYS-CORE in action: contextual planning and edits inside a real codebase.</em></p>

RAYS-CORE is an AI coding assistant for local repositories. It indexes your codebase, retrieves relevant symbols and files, plans changes, applies edits with permission controls, and maintains persistent project memory.

Why RAYS-CORE

• Works on real codebases with structural indexing and symbol-level retrieval.
• Supports read-only chat, targeted editing, and new-project generation in one CLI.
• Provider-flexible: local-first with Ollama, plus Gemini API support.
• Tracks context over time through .rays memory and summaries.

Features

• Codebase indexing (files, symbols, relationships, boundaries) via msgpack registries.
• ChromaDB-backed vector retrieval for relevant chunks.
• Multi-stage edit pipeline: task analysis -> selection -> planning -> permissions -> apply.
• Interactive slash commands (/chat, /model, /mode, /git, /help).
• Session-aware API key handling (reads env vars first; never persists keys in config.yaml).

Supported Providers

• Ollama (local)
  • Default local endpoint: http://localhost:11434
  • By default, RAYS expects Ollama to be running on port 11434 unless you configure a different endpoint.
• Gemini API
  • Uses GEMINI_API_KEY (or fallback GOOGLE_API_KEY).

Some builds may still show additional provider options in the selector, but this repository release is documented and supported around Ollama and Gemini.

Environment Variables

RAYS checks environment variables before prompting for API keys.

• GEMINI_API_KEY: Gemini API key (preferred for Gemini)
• GOOGLE_API_KEY: Gemini fallback key if GEMINI_API_KEY is not set

macOS/Linux (zsh/bash)

export GEMINI_API_KEY="your_gemini_key"

To make permanent in zsh:

echo 'export GEMINI_API_KEY="your_gemini_key"' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell)

setx GEMINI_API_KEY "your_gemini_key"

Open a new terminal after setx.

Installation

Option A: pipx (recommended for CLI users)

pipx install rays-core

Upgrade later with:

pipx upgrade rays-core

Option B: pip

pip install rays-core

Upgrade later with:

pip install --upgrade rays-core

Development install from source

git clone https://github.com/markknoffler/RAYS-CORE-CLI.git
cd RAYS-CORE-CLI
python -m pip install -e .

Quick Start

rays /path/to/your/codebase

Or inside a repository:

cd /path/to/your/codebase
rays

Screenshots / Demo Gallery

Create a folder for README assets:

docs/images/

Then add your screenshots and reference them like this:

## Screenshots

### 1) Planning + analysis flow
![RAYS planning flow](docs/images/rays-planning.png)

### 2) Code edit execution flow
![RAYS edit flow](docs/images/rays-editing.png)

If you want side-by-side images:

<p align="center">
  <img src="docs/images/rays-planning.png" alt="RAYS planning" width="49%" />
  <img src="docs/images/rays-editing.png" alt="RAYS editing" width="49%" />
</p>

Recommended filenames:

• docs/images/rays-hero.png
• docs/images/rays-planning.png
• docs/images/rays-editing.png
• docs/images/rays-chat.png

The 3 Operating Modes

RAYS-CORE supports three workflow modes in practice:

1. Editing mode (default pipeline)

   • Trigger: normal prompt without /chat.
   • Behavior: analyzes task, identifies symbols/files, negotiates permissions, plans edits, applies changes.

2. New codebase generation mode

   • Trigger: prompts that clearly request creating a new project and low structural dependency on existing code.
   • Behavior: sets up project structure, negotiates creation scope, generates files iteratively.

3. Chat mode (/chat)

   • Trigger: /chat <question>.
   • Behavior: read-only contextual Q&A; no edit pipeline.

Prompting Guide

Editing mode prompts (normal chat input)

• "Refactor authentication middleware to support JWT refresh tokens."
• "Fix the bug where user profile update fails on missing avatar."
• "Add caching around get_project_metrics and include invalidation."

New codebase creation prompts

• "Create a new FastAPI project with JWT auth, PostgreSQL, and Alembic migrations."
• "Generate a minimal React + TypeScript dashboard app with routing and auth pages."

Chat mode prompts

Use:

/chat how does the permission negotiation pipeline work in this repo?

Slash Commands

• /help - show commands
• /chat <question> - read-only contextual Q&A
• /model <name> - switch model
• /mode auto - autonomous command execution
• /mode ask - ask-permission command execution
• /git - summarize current git changes
• /clear - clear screen
• /exit - exit RAYS

Execution Behavior (/mode)

• Ask mode: requests confirmation for terminal actions.
• Autonomous mode: executes without per-command confirmation.

Pipeline Architecture

1. Provider + model selection
2. Indexing of files/symbols/relationships/boundaries
3. Vector DB sync for semantic retrieval
4. Task analysis (intent, scope, terminal needs)
5. Symbol detection and candidate retrieval
6. Planning and permission negotiation
7. Anchoring + code generation
8. Execution and post-edit terminal actions
9. Memory + summary persistence

Core modules:

• rays_main.py - orchestrator and CLI loop
• task_analyzer.py - intent and scope analysis
• symbol_detection.py - symbol selection and retrieval
• planning.py - implementation planning
• execution.py + code_generator.py - code application
• memory.py - persistent memory and summaries

Configuration

Primary configuration file: config.yaml

Key sections:

• llm - provider, model, endpoint, runtime key override
• embedding - embedding provider/model/endpoint
• execution_mode - default ask or autonomous

config.yaml values are startup defaults. During CLI startup, selected provider/model values are updated and persisted automatically.

RAYS intentionally clears persisted API keys in config and uses runtime/session keys.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for setup, branch hygiene, PR expectations, and review checklist.

Security

If you discover a security issue, see SECURITY.md for reporting guidance.

License

MIT License. See LICENSE.

Publishing Notes (Maintainers)

Build package

python -m pip install --upgrade build twine
python -m build
twine check dist/*

Publish to PyPI

python -m twine upload dist/*

Recommended install command for users

pipx install rays-core

Published package:

• rays-core on PyPI