swadhin / mervelas public

docs: finalize project documentation, branding assets, and guidelines

Swadhin Biswas committed 6 months ago
4507ba8
1 parent 0358986
commit 4507ba8
6 files changed
+169 -0
Showing 6 changed files+169-0
.github/copilot-instructions.mdREADME.mdimages/agentcreate.pngimages/config.pngimages/context.pngimages/lunchpage.png
▼.github/copilot-instructions.md
+29-0
@@ -0,0 +1,29 @@
1
+# Mervelas Developer Guidelines
2
+
3
+Welcome to the Mervelas codebase! Mervelas is a fast, local-first AI coding CLI written in React (Ink) and compiled with Bun. Follow these specific strategies to stay productive and aligned with project architecture:
4
+
5
+## 1. Project Architecture & Tooling
6
+
7
+- **Custom UI System:** Mervelas uses a highly custom, optimized implementation of Ink for rendering the CLI interface.
8
+ - **CRITICAL:** **Never import `ink` directly from npm.** Always import layout components (`Box`, `Text`) and hooks from `src/ink.ts`, `src/ink.tsx`, or `src/ink/index.ts`.
9
+- **AI Integrations:** The codebase speaks to LLM APIs (OpenAI, OpenRouter) and defines agent capabilities using `@anthropic-ai/sdk` and Model Context Protocol (`@modelcontextprotocol/sdk`).
10
+- **Bridge Sync/Daemon:** The `src/bridge/` folder abstracts away remote daemons, environments (Chromium, bash tasks), and external environment APIs.
11
+- **Build Workflows:** We use `bun` as the package manager and bundler. The build script (`scripts/build.ts`) uses extreme size optimization strategies like module stubbing (`namespace: text-stub`, `namespace: native-stub` or internal feature stripping). Keep dependencies lightweight.
12
+
13
+## 2. Developer Constraints & Conventions
14
+
15
+- **CLI Startup Speed & Lazy Loading:**
16
+ - Avoiding top-level side effects is paramount. Do not execute heavy logic, file reads, or instantiate state singletons on load.
17
+ - See `src/main.tsx` for usage of `profileCheckpoint(...)` to measure startup bounds.
18
+ - **Commands (defined in `src/commands/...`) should be lazy-loaded:** The `load: () => import('./my-command.js')` pattern keeps startup overhead strictly on a "need-to-execute" basis.
19
+- **Agent Tools (`src/tools/...`):** Tools are structured as React components that implement both the AI execution logic (often matching an MCP schema) and an interactive CLI UI/result view (e.g., `BashTool.tsx`, `BashToolResultMessage.tsx`).
20
+- **Formatting:** Keep in mind the codebase uses Biome rules in certain places (`// biome-ignore-all ...`). Follow strictly the formatting present in the file you edit.
21
+
22
+## 3. Recommended Workflows
23
+
24
+- **Building the Extension:** `bun run build`. (Also used via `npm run build` or `npm start` over `dist/cli.mjs`).
25
+- **Testing Logic:** Test critical logic via `bun test src/...` and catch type errors using `npm run typecheck` (`tsc --noEmit`).
26
+- **Performance Tooling:** Since `.perf-artifacts/` are relied upon, any changes to slow workflows like startup execution or initial queries MUST be profiled using:
27
+ - `bun run perf:startup --` (Check Idle CPU, RSS memory)
28
+ - `bun run perf:query --`
29
+ - (Check `PERFORMANCE.md` for our specific baselining methodology before raising performance-impacting UI elements).
0
30
▼README.md
+140-0
@@ -0,0 +1,140 @@
1
+<div align="center">
2
+
3
+```text
4
+ █▄ ▄█
5
+ ███████
6
+ █ ▀ ▀ █
7
+```
8
+
9
+# Mervelas
10
+
11
+**The Fast, Unlocked, Local-First AI Coding Assistant.**
12
+
13
+[![Bun Built](https://img.shields.io/badge/Built_with-Bun-black)](https://bun.sh)
14
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](#license)
15
+
16
+_Note: Mervelas is currently in active development. We have not published to NPM yet. You need to build the project locally and carefully use your own API keys. Stay tuned for official releases!_
17
+
18
+</div>
19
+
20
+---
21
+
22
+## 🌟 Welcome to Mervelas
23
+
24
+Mervelas is an independent, open-source AI coding CLI built from the ground up to guarantee freedom, zero telemetry, and maximum performance.
25
+
26
+Many enterprise assistants try to force developers into a single closed ecosystem or silently harvest usage telemetry. We firmly believe your code, your terminal, and your prompts belong to you.
27
+
28
+### Why Choose Mervelas?
29
+
30
+1. **Provider Independence:** We break the chains. Mervelas fully supports OpenAI, OpenRouter, NVIDIA NIM, Qwen, DeepSeek, and locally hosted models out of the box.
31
+2. **Unified Native Commands:** Forget heavily patched forks that break `/skills` or `/login`. Mervelas provides flawlessly integrated commands deeply connected to the local event loop.
32
+3. **Extremely Lightweight:** Compiled natively with `bun` and rendered via a highly optimized custom React Ink abstraction. It has almost **zero idle CPU usage** and lightning-quick startup latencies.
33
+4. **Absolute Privacy:** Session architectures are strictly localized. Your conversational history is written securely to `~/.mervelas/projects/` locally via JSONL formatting, ensuring sensitive projects never leak metadata.
34
+
35
+---
36
+
37
+## 📸 See It In Action
38
+
39
+<div align="center">
40
+ <table>
41
+ <tr>
42
+ <td align="center">
43
+ <b>Launch Interface</b><br>
44
+ <img src="images/lunchpage.png" alt="Mervelas Launch Page" width="400"/>
45
+ </td>
46
+ <td align="center">
47
+ <b>Smart Context Management</b><br>
48
+ <img src="images/context.png" alt="Mervelas Context" width="400"/>
49
+ </td>
50
+ </tr>
51
+ <tr>
52
+ <td align="center">
53
+ <b>Configuration & Settings</b><br>
54
+ <img src="images/config.png" alt="Mervelas Config" width="400"/>
55
+ </td>
56
+ <td align="center">
57
+ <b>Custom Agent Creation</b><br>
58
+ <img src="images/agentcreate.png" alt="Mervelas Custom Agents" width="400"/>
59
+ </td>
60
+ </tr>
61
+ </table>
62
+</div>
63
+
64
+---
65
+
66
+## 🚀 Compile & Run Locally
67
+
68
+To get started with Mervelas today, you'll need to compile it from the source using Bun.
69
+
70
+### 1. Prerequisites
71
+
72
+Mervelas requires [Bun](https://bun.sh) to compile gracefully and run smoothly on your local machine.
73
+
74
+### 2. Setup Guide
75
+
76
+```bash
77
+# Clone the repository
78
+git clone https://github.com/swadhinbiswas/Mervelas.git
79
+cd Mervelas
80
+
81
+# Install native dependencies
82
+bun install
83
+
84
+# Compile the CLI via the internal bundler
85
+bun run scripts/build.ts
86
+
87
+# Execute Mervelas
88
+node dist/cli.mjs
89
+```
90
+
91
+### 3. Provider Configuration
92
+
93
+Once running, simply execute `/config` or `/login` in the prompt to set up your LLM provider and paste your API key. That's it!
94
+
95
+---
96
+
97
+## 🛠️ Essential Commands
98
+
99
+Mervelas offers a rich suite of integrated workflows. Inside the CLI, try out:
100
+
101
+- `/config` — Configure your LLM providers, manage API keys, and tweak models.
102
+- `/context` — View exact token usage and visualize your context window limits cleanly.
103
+- `/agents` — Create and switch between highly specific local coding agents seamlessly.
104
+- `/mcp` — Integrate **Model Context Protocol** (MCP) servers locally to give your model superpowered access to other applications.
105
+- `/status` — View your local development state or system resource consumption.
106
+- `/login` — Swiftly swap backends and models locally.
107
+
108
+---
109
+
110
+## 💻 Environment Configuration
111
+
112
+For headless setups and CI workflows, rely on environment variables:
113
+
114
+```bash
115
+# OpenAI or NIM setup
116
+MERVELAS_API_PROVIDER=openai
117
+OPENAI_API_KEY=your_key_here
118
+OPENAI_BASE_URL=https://api.openai.com/v1
119
+
120
+# OpenRouter setup
121
+MERVELAS_API_PROVIDER=openroute
122
+OPENROUTER_API_KEY=your_key_here
123
+OPENROUTER_BASE_URL=https://openrouter.ai/api
124
+```
125
+
126
+---
127
+
128
+## 🏗️ Contributing & Development Boundaries
129
+
130
+If you are contributing patches or developing advanced features for Mervelas, please adhere to these core rules to avoid DMCA cross-overs or architectural regressions:
131
+
132
+- **Custom UI System:** Never directly import `ink` blindly from npm. Mervelas relies securely on layout structures (`Box`, `Text`) routed strictly through `src/ink.ts`.
133
+- **Top-Level Pure Behavior:** Do _not_ instantiate blocking state singletons or file reads on file-load. Tools and execute loops must use the `load: () => import(...)` delay abstraction so that the CLI footprint remains completely idle until actively invoked.
134
+- **Type Checking:** Continuously test strict ES2023 adherence using `npm run typecheck` (`tsc --noEmit`).
135
+
136
+<br>
137
+
138
+<div align="center">
139
+<i>Built for developers who demand complete sovereignty over their workflows.</i>
140
+</div>
0
141
▼images/agentcreate.png
+0-0
Binary file not shown.
▼images/config.png
+0-0
Binary file not shown.
▼images/context.png
+0-0
Binary file not shown.
▼images/lunchpage.png
+0-0
Binary file not shown.