1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362# Contributing to OpenFang
Thank you for your interest in contributing to OpenFang. This guide covers everything you need to get started, from setting up your development environment to submitting pull requests.
## Table of Contents
- [Development Environment](#development-environment)
- [Building and Testing](#building-and-testing)
- [Code Style](#code-style)
- [Architecture Overview](#architecture-overview)
- [How to Add a New Agent Template](#how-to-add-a-new-agent-template)
- [How to Add a New Channel Adapter](#how-to-add-a-new-channel-adapter)
- [How to Add a New Tool](#how-to-add-a-new-tool)
- [Pull Request Process](#pull-request-process)
- [Code of Conduct](#code-of-conduct)
---
## Development Environment
### Prerequisites
- **Rust 1.75+** (install via [rustup](https://rustup.rs/))
- **Git**
- **Python 3.8+** (optional, for Python runtime and skills)
- A supported LLM API key (Anthropic, OpenAI, Groq, etc.) for end-to-end testing
### Clone and Build
```bash
git clone https://github.com/RightNow-AI/openfang.git
cd openfang
cargo build
```
The first build takes a few minutes because it compiles SQLite (bundled) and Wasmtime. Subsequent builds are incremental.
### Environment Variables
For running integration tests that hit a real LLM, set at least one provider key:
```bash
export GROQ_API_KEY=gsk_... # Recommended for fast, free-tier testing
export ANTHROPIC_API_KEY=sk-ant-... # For Anthropic-specific tests
```
Tests that require a real LLM key will skip gracefully if the env var is absent.
---
## Building and Testing
### Build the Entire Workspace
```bash
cargo build --workspace
```
### Run All Tests
```bash
cargo test --workspace
```
The test suite is currently 1,744+ tests. All must pass before merging.
### Run Tests for a Single Crate
```bash
cargo test -p openfang-kernel
cargo test -p openfang-runtime
cargo test -p openfang-memory
```
### Check for Clippy Warnings
```bash
cargo clippy --workspace --all-targets -- -D warnings
```
The CI pipeline enforces zero clippy warnings.
### Format Code
```bash
cargo fmt --all
```
Always run `cargo fmt` before committing. CI will reject unformatted code.
### Run the Doctor Check
After building, verify your local setup:
```bash
cargo run -- doctor
```
---
## Code Style
- **Formatting**: Use `rustfmt` with default settings. Run `cargo fmt --all` before every commit.
- **Linting**: `cargo clippy --workspace -- -D warnings` must pass with zero warnings.
- **Documentation**: All public types and functions must have doc comments (`///`).
- **Error Handling**: Use `thiserror` for error types. Avoid `unwrap()` in library code; prefer `?` propagation.
- **Naming**:
- Types: `PascalCase` (e.g., `OpenFangKernel`, `AgentManifest`)
- Functions/methods: `snake_case`
- Constants: `SCREAMING_SNAKE_CASE`
- Crate names: `openfang-{name}` (kebab-case)
- **Dependencies**: Workspace dependencies are declared in the root `Cargo.toml`. Prefer reusing workspace deps over adding new ones. If you need a new dependency, justify it in the PR.
- **Testing**: Every new feature must include tests. Use `tempfile::TempDir` for filesystem isolation and random port binding for network tests.
- **Serde**: All config structs use `#[serde(default)]` for forward compatibility with partial TOML.
---
## Architecture Overview
OpenFang is organized as a Cargo workspace with 14 crates:
| Crate | Role |
|-------|------|
| `openfang-types` | Shared type definitions, taint tracking, manifest signing (Ed25519), model catalog, MCP/A2A config types |
| `openfang-memory` | SQLite-backed memory substrate with vector embeddings, usage tracking, canonical sessions, JSONL mirroring |
| `openfang-runtime` | Agent loop, 3 LLM drivers (Anthropic/Gemini/OpenAI-compat), 38 built-in tools, WASM sandbox, MCP client/server, A2A protocol |
| `openfang-hands` | Hands system (curated autonomous capability packages), 7 bundled hands |
| `openfang-extensions` | Integration registry (25 bundled MCP templates), AES-256-GCM credential vault, OAuth2 PKCE |
| `openfang-kernel` | Assembles all subsystems: workflow engine, RBAC auth, heartbeat monitor, cron scheduler, config hot-reload |
| `openfang-api` | REST/WS/SSE API (Axum 0.8), 76 endpoints, 14-page SPA dashboard, OpenAI-compatible `/v1/chat/completions` |
| `openfang-channels` | 40 channel adapters (Telegram, Discord, Slack, WhatsApp, and 36 more), formatter, rate limiter |
| `openfang-wire` | OFP (OpenFang Protocol): TCP P2P networking with HMAC-SHA256 mutual authentication |
| `openfang-cli` | Clap CLI with daemon auto-detect (HTTP mode vs. in-process fallback), MCP server |
| `openfang-migrate` | Migration engine for importing from OpenClaw (and future frameworks) |
| `openfang-skills` | Skill system: 60 bundled skills, FangHub marketplace, OpenClaw compatibility, prompt injection scanning |
| `openfang-desktop` | Tauri 2.0 native desktop app (WebView + system tray + single-instance + notifications) |
| `xtask` | Build automation tasks |
### Key Architectural Patterns
- **`KernelHandle` trait**: Defined in `openfang-runtime`, implemented on `OpenFangKernel` in `openfang-kernel`. This avoids circular crate dependencies while enabling inter-agent tools.
- **Shared memory**: A fixed UUID (`AgentId(Uuid::from_bytes([0..0, 0x01]))`) provides a cross-agent KV namespace.
- **Daemon detection**: The CLI checks `~/.openfang/daemon.json` and pings the health endpoint. If a daemon is running, commands use HTTP; otherwise, they boot an in-process kernel.
- **Capability-based security**: Every agent operation is checked against the agent's granted capabilities before execution.
---
## How to Add a New Agent Template
Agent templates live in the `agents/` directory. Each template is a folder containing an `agent.toml` manifest.
### Steps
1. Create a new directory under `agents/`:
```
agents/my-agent/agent.toml
```
2. Write the manifest:
```toml
name = "my-agent"
version = "0.1.0"
description = "A brief description of what this agent does."
author = "openfang"
module = "builtin:chat"
tags = ["category"]
[model]
provider = "groq"
model = "llama-3.3-70b-versatile"
[resources]
max_llm_tokens_per_hour = 100000
[capabilities]
tools = ["file_read", "file_list", "web_fetch"]
memory_read = ["*"]
memory_write = ["self.*"]
agent_spawn = false
```
3. Include a system prompt if needed by adding it to the `[model]` section:
```toml
[model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
system_prompt = """
You are a specialized agent that...
"""
```
4. Test by spawning:
```bash
openfang agent spawn agents/my-agent/agent.toml
```
5. Submit a PR with the new template.
---
## How to Add a New Channel Adapter
Channel adapters live in `crates/openfang-channels/src/`. Each adapter implements the `ChannelAdapter` trait.
### Steps
1. Create a new file: `crates/openfang-channels/src/myplatform.rs`
2. Implement the `ChannelAdapter` trait (defined in `types.rs`):
```rust
use crate::types::{ChannelAdapter, ChannelMessage, ChannelType};
use async_trait::async_trait;
pub struct MyPlatformAdapter {
// token, client, config fields
}
#[async_trait]
impl ChannelAdapter for MyPlatformAdapter {
fn channel_type(&self) -> ChannelType {
ChannelType::Custom("myplatform".to_string())
}
async fn start(&mut self) -> Result<(), Box<dyn std::error::Error>> {
// Start polling/listening for messages
Ok(())
}
async fn send(&self, channel_id: &str, content: &str) -> Result<(), Box<dyn std::error::Error>> {
// Send a message back to the platform
Ok(())
}
async fn stop(&mut self) {
// Clean shutdown
}
}
```
3. Register the module in `crates/openfang-channels/src/lib.rs`:
```rust
pub mod myplatform;
```
4. Wire it up in the channel bridge (`crates/openfang-api/src/channel_bridge.rs`) so the daemon starts it alongside other adapters.
5. Add configuration support in `openfang-types` config structs (add a `[channels.myplatform]` section).
6. Add CLI setup wizard instructions in `crates/openfang-cli/src/main.rs` under `cmd_channel_setup`.
7. Write tests and submit a PR.
---
## How to Add a New Tool
Built-in tools are defined in `crates/openfang-runtime/src/tool_runner.rs`.
### Steps
1. Add the tool implementation function:
```rust
async fn tool_my_tool(input: &serde_json::Value) -> Result<String, String> {
let param = input["param"]
.as_str()
.ok_or("Missing 'param' field")?;
// Tool logic here
Ok(format!("Result: {param}"))
}
```
2. Register it in the `execute_tool` match block:
```rust
"my_tool" => tool_my_tool(input).await,
```
3. Add the tool definition to `builtin_tool_definitions()`:
```rust
ToolDefinition {
name: "my_tool".to_string(),
description: "Description shown to the LLM.".to_string(),
input_schema: serde_json::json!({
"type": "object",
"properties": {
"param": {
"type": "string",
"description": "The parameter description"
}
},
"required": ["param"]
}),
},
```
4. Agents that need the tool must list it in their manifest:
```toml
[capabilities]
tools = ["my_tool"]
```
5. Write tests for the tool function.
6. If the tool requires kernel access (e.g., inter-agent communication), accept `Option<&Arc<dyn KernelHandle>>` and handle the `None` case gracefully.
---
## Pull Request Process
1. **Fork and branch**: Create a feature branch from `main`. Use descriptive names like `feat/add-matrix-adapter` or `fix/session-restore-crash`.
2. **Make your changes**: Follow the code style guidelines above.
3. **Test thoroughly**:
- `cargo test --workspace` must pass (all 1,744+ tests).
- `cargo clippy --workspace --all-targets -- -D warnings` must produce zero warnings.
- `cargo fmt --all --check` must produce no diff.
4. **Write a clear PR description**: Explain what changed and why. Include before/after examples if applicable.
5. **One concern per PR**: Keep PRs focused. A single PR should address one feature, one bug fix, or one refactor -- not all three.
6. **Review process**: At least one maintainer must approve before merge. Address review feedback promptly.
7. **CI must pass**: All automated checks must be green before merge.
### Commit Messages
Use clear, imperative-mood messages:
```
Add Matrix channel adapter with E2EE support
Fix session restore crash on kernel reboot
Refactor capability manager to use DashMap
```
---
## Code of Conduct
This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By participating, you agree to uphold a welcoming, inclusive, and harassment-free environment for everyone.
Please report unacceptable behavior to the maintainers.
---
## Questions?
- Open a [GitHub Discussion](https://github.com/RightNow-AI/openfang/discussions) for questions.
- Open a [GitHub Issue](https://github.com/RightNow-AI/openfang/issues) for bugs or feature requests.
- Check the [docs/](docs/) directory for detailed guides on specific topics.