JohnRiceML

Contributing to ClawPort

Development community intermediate

SOURCE https://github.com/JohnRiceML/clawport-ui

Description

Thank you for your interest in contributing to ClawPort. Whether you are fixing a bug, improving documentation, or adding a feature, your help is welcome and appreciated. This guide covers the convent

Installation

This entry records only its repository, not the path inside it, so there is no exact command to give. Open the source below and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

Repository README

This is the README for JohnRiceML/clawport-ui, shared by 4 entries in this directory. It describes the repository, not this entry specifically.

Contributing to ClawPort

Thank you for your interest in contributing to ClawPort. Whether you are fixing a bug, improving documentation, or adding a feature, your help is welcome and appreciated.

This guide covers the conventions and process we follow so that contributions stay consistent and easy to review.

Scope & Policy

Before opening a PR, please understand what ClawPort is and is not:

ClawPort is a UI layer. It renders data from OpenClaw. It does not execute agents, manage cron jobs, or handle orchestration. Features that belong in the OpenClaw runtime should be contributed upstream at openclaw.ai.
English-first. All UI strings, error messages, log labels, and documentation must be in English. We do not accept localization or i18n PRs at this time.
No server-side string changes without maintainer approval. Agent registry names, AI system prompts, and slash command text are carefully tuned -- changes need discussion first.

What we will not merge

To save everyone time, here are PR types we will close without review:

Localization / i18n -- adding translations, non-English strings, or internationalization infrastructure
Docs rewrites -- wholesale restructuring of existing documentation (small fixes and additions are welcome)
Bundled scope creep -- PRs that mix unrelated changes (e.g., a feature + a refactor + formatting fixes)
Server-side string changes -- modifying agent names, AI prompts, or slash command text without prior discussion
Features that belong in OpenClaw -- agent execution, gateway protocol changes, new CLI commands

See [docs/OPENCLAW.md](docs/OPENCLAW.md) for a detailed breakdown of what belongs in ClawPort vs OpenClaw.

Development Setup

Fork and clone the repository:

git clone https://github.com//clawport-ui.git
cd clawport-ui

Install dependencies (Node 22+):
```
npm install
```
Run the setup script to auto-detect your local OpenClaw installation and generate `.env.local`:
```
npm run setup
```
Start the dev server (Turbopack, port 3000):
```
npm run dev
```

Code Style

ClawPort follows a small set of conventions that keep the codebase consistent. Please follow these when writing new code:

TypeScript strict mode. No any escapes without a comment explaining why.
Tailwind CSS custom properties for theming. Use var(--text-primary), var(--bg), etc. instead of Tailwind color utility classes like text-gray-500. Theme tokens are defined in app/globals.css.
No external charting or media libraries. Use native Web APIs (Canvas, SVG, MediaRecorder, AudioContext) and custom components.
Base64 data URLs for persisted media. Blob URLs do not survive page reloads. Always convert to base64 before storing.
Call requireEnv() inside functions, not at module top level. Top-level calls crash imports during next build