Skip to content

Commit be871aa

Browse files
chriswritescode-devchriswritescode-dev
authored
Readme redesign (#146)
* Redesign README for improved GitHub rendering * Fix release badge URL format * Add .env setup to Quick Start and update config examples * Add Git Commit Demo GIF * Fix release badge to use tag endpoint * update development docs and fix default port in env * Enhance Docker documentation with environment variables and entrypoint behavior * Expand Memory plugin documentation with architecture, agents, and hooks * Add dark mode CSS and configure MkDocs for dark-only theme
1 parent a911a2f commit be871aa

8 files changed

Lines changed: 715 additions & 545 deletions

File tree

‎.env.example‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
# ============================================
66
# Backend Server Configuration
77
# ============================================
8-
PORT=5001
8+
PORT=5003
99
HOST=0.0.0.0
1010
CORS_ORIGIN=http://localhost:5173
1111
NODE_ENV=production
@@ -109,8 +109,7 @@ PASSKEY_ORIGIN=http://localhost:5003
109109
# Frontend Configuration (Vite)
110110
# These are optional - frontend uses defaults if not set
111111
# ============================================
112-
# VITE_API_URL=http://localhost:5001
113-
# VITE_SERVER_PORT=5001
112+
# VITE_API_URL=http://localhost:5003
114113
# VITE_OPENCODE_PORT=5551
115114
# VITE_MAX_FILE_SIZE_MB=50
116115
# VITE_MAX_UPLOAD_SIZE_MB=50

‎README.md‎

Lines changed: 44 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -2,208 +2,89 @@
22
<img src=".github/social-preview.png" alt="OpenCode Manager" width="600" style="border: none" />
33
</p>
44

5-
# OpenCode Manager
5+
<p align="center">
6+
<strong>Mobile-first web interface for <a href="https://opencode.ai">OpenCode</a> AI agents. Manage, control, and code from any device.</strong>
7+
</p>
68

7-
Mobile-first web interface for [OpenCode](https://opencode.ai) AI agents. Manage, control, and code from any device - your phone, tablet, or desktop.
9+
<p align="center">
10+
<a href="https://github.com/chriswritescode-dev/opencode-manager/blob/main/LICENSE">
11+
<img src="https://img.shields.io/github/license/chriswritescode-dev/opencode-manager?label=License" alt="License" />
12+
</a>
13+
<a href="https://github.com/chriswritescode-dev/opencode-manager/stargazers">
14+
<img src="https://img.shields.io/github/stars/chriswritescode-dev/opencode-manager?label=Stars" alt="Stars" />
15+
</a>
16+
<a href="https://github.com/chriswritescode-dev/opencode-manager/releases/latest">
17+
<img src="https://img.shields.io/github/v/tag/chriswritescode-dev/opencode-manager" alt="Latest Release" />
18+
</a>
19+
<a href="https://github.com/chriswritescode-dev/opencode-manager/pulls">
20+
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome" />
21+
</a>
22+
</p>
823

9-
<!-- Replace with your hero GIF showing the main workflow -->
1024
<p align="center">
1125
<img src="docs/images/ocmgr-demo.gif" alt="OpenCode Manager Demo" height="400" />
26+
<img src="https://github.com/user-attachments/assets/c8087451-8b97-4178-952b-b8149f5c258a" alt="Git Commit Demo" height="400" />
1227
</p>
1328

1429
## Quick Start
1530

1631
```bash
1732
git clone https://github.com/chriswritescode-dev/opencode-manager.git
1833
cd opencode-manager
34+
cp .env.example .env
1935
docker-compose up -d
2036
# Open http://localhost:5003
2137
```
2238

2339
On first launch, you'll be prompted to create an admin account. That's it!
2440

41+
For local development setup, see the [Development Guide](https://chriswritescode-dev.github.io/opencode-manager/development/setup/).
42+
2543
## Screenshots
2644

2745
<table>
2846
<tr>
29-
<td><strong>Chat (Mobile)</strong></td>
30-
</tr>
31-
<tr>
32-
<td><img src="https://github.com/user-attachments/assets/a48cc728-e540-4247-879a-c5f36c3fd6de" alt="chat-mobile" width="200" /></td>
33-
</tr>
34-
<tr>
35-
<td><strong>File Browser (Mobile)</strong></td>
36-
</tr>
37-
<tr>
38-
<td><img src="https://github.com/user-attachments/assets/24243e5e-ab02-44ff-a719-263f61c3178b" alt="files-mobile" width="200" /></td>
39-
</tr>
40-
<tr>
41-
<td><strong>Inline Diff View</strong></td>
42-
</tr>
43-
<tr>
44-
<td><img src="https://github.com/user-attachments/assets/b94c0ca0-d960-4888-8a25-a31ed6d5068d" alt="inline-diff-view" width="300" /></td>
47+
<td align="center"><strong>Chat (Mobile)</strong><br/><img src="https://github.com/user-attachments/assets/a48cc728-e540-4247-879a-c5f36c3fd6de" alt="chat-mobile" width="200" /></td>
48+
<td align="center"><strong>File Browser (Mobile)</strong><br/><img src="https://github.com/user-attachments/assets/24243e5e-ab02-44ff-a719-263f61c3178b" alt="files-mobile" width="200" /></td>
49+
<td align="center"><strong>Inline Diff View</strong><br/><img src="https://github.com/user-attachments/assets/b94c0ca0-d960-4888-8a25-a31ed6d5068d" alt="inline-diff-view" width="300" /></td>
4550
</tr>
4651
</table>
4752

4853
## Features
4954

50-
### Repository & Git
51-
- **Multi-Repository Support** - Clone and manage multiple git repos with private repo support via GitHub PAT
52-
- **SSH Authentication** - SSH key authentication for git repositories
53-
- **Git Worktrees** - Work on multiple branches simultaneously
54-
- **Source Control Panel** - View changes, commits, and branches in a unified interface
55-
- **Diff Viewer** - Unified diffs with line numbers and change counts
56-
- **Push PRs** - Create and push pull requests directly from the UI
57-
58-
### File Management
59-
- **Directory Browser** - Navigate files with tree view and search
60-
- **Syntax Highlighting** - Code preview with highlighting for all major languages
61-
- **File Operations** - Create, rename, delete, and drag-and-drop upload
62-
- **ZIP Download** - Download repos as ZIP (respects .gitignore)
63-
64-
### Chat & Sessions
65-
- **Real-time Streaming** - Live message streaming with SSE
66-
- **Slash Commands** - Built-in (`/help`, `/new`, `/compact`) and custom commands
67-
- **File Mentions** - Reference files with `@filename` autocomplete
68-
- **Plan/Build Modes** - Toggle between read-only and file-change modes
69-
- **Mermaid Diagrams** - Visual diagram rendering in chat
70-
- **Text-to-Speech** - Listen to AI responses with browser or OpenAI-compatible TTS
71-
- **Speech-to-Text** - Dictate messages using browser speech recognition or OpenAI-compatible STT
72-
73-
### AI Configuration
74-
- **Model Selection** - Browse and filter available AI models
75-
- **Provider Management** - Configure API keys or OAuth for providers
76-
- **OAuth Support** - Secure OAuth login for Anthropic and GitHub Copilot
77-
- **Custom Agents** - Create agents with custom system prompts and tool permissions
78-
- **MCP Servers** - Add local or remote MCP servers with pre-built templates
79-
- **Memory Plugin** - Persistent project knowledge with semantic search, planning state, and compaction awareness
80-
81-
### Mobile & PWA
82-
- **Mobile-First Design** - Responsive UI optimized for mobile
83-
- **PWA Installable** - Add to home screen on any device
84-
- **iOS Optimized** - Proper keyboard handling and swipe navigation
85-
- **Push Notifications** - Background alerts for agent events when app is closed
86-
87-
## Installation
88-
89-
### Docker (Recommended)
90-
91-
```bash
92-
git clone https://github.com/chriswritescode-dev/opencode-manager.git
93-
cd opencode-manager
94-
docker-compose up -d
95-
```
96-
97-
The container automatically installs OpenCode, builds the frontend, and sets up persistent volumes.
98-
99-
**Common commands:**
100-
```bash
101-
docker-compose up -d # Start
102-
docker-compose down # Stop
103-
docker-compose logs -f # View logs
104-
docker-compose restart # Restart
105-
```
106-
107-
### Local Development
108-
109-
For contributors who want to develop locally:
110-
111-
```bash
112-
# Prerequisites: pnpm, Bun, OpenCode TUI (npm i -g @opencode/tui)
113-
114-
git clone https://github.com/chriswritescode-dev/opencode-manager.git
115-
cd opencode-manager
116-
pnpm install
117-
cp .env.example .env
118-
pnpm dev
119-
```
55+
- **Git** — Multi-repo support, SSH authentication, worktrees, unified diffs with line numbers, PR creation
56+
- **Files** — Directory browser with tree view, syntax highlighting, create/rename/delete, ZIP download
57+
- **Chat** — Real-time streaming (SSE), slash commands, `@file` mentions, Plan/Build modes, Mermaid diagrams
58+
- **Audio** — Text-to-speech (browser + OpenAI-compatible), speech-to-text (browser + OpenAI-compatible)
59+
- **AI** — Model selection, provider config, OAuth for Anthropic/GitHub Copilot, custom agents with system prompts
60+
- **MCP** — Local and remote MCP server support with pre-built templates
61+
- **Memory** — Persistent project knowledge with semantic search, planning state, and compaction awareness
62+
- **Mobile** — Responsive UI, PWA installable, iOS-optimized with proper keyboard handling and swipe navigation
12063

12164
## Configuration
12265

123-
### Authentication
124-
125-
OpenCode Manager uses single-user authentication. Create your admin account on first launch, or pre-configure via environment variables:
126-
12766
```bash
128-
# Pre-configured admin (optional)
129-
ADMIN_EMAIL=admin@example.com
130-
ADMIN_PASSWORD=your-secure-password
131-
13267
# Required for production
13368
AUTH_SECRET=your-secure-random-secret # Generate with: openssl rand -base64 32
134-
```
135-
136-
### Remote/LAN Access
137-
138-
For HTTP access on local networks:
139-
140-
```bash
141-
AUTH_TRUSTED_ORIGINS=http://localhost:5003
142-
AUTH_SECURE_COOKIES=false # Required when not using HTTPS (cookies won't work over plain HTTP otherwise)
143-
```
144-
145-
### OAuth Providers (Optional)
146-
147-
Enable social login by configuring OAuth credentials:
148-
149-
```bash
150-
# GitHub
151-
GITHUB_CLIENT_ID=...
152-
GITHUB_CLIENT_SECRET=...
153-
154-
# Google
155-
GOOGLE_CLIENT_ID=...
156-
GOOGLE_CLIENT_SECRET=...
157-
158-
# Discord
159-
DISCORD_CLIENT_ID=...
160-
DISCORD_CLIENT_SECRET=...
161-
```
16269

163-
### Passkeys
164-
165-
For WebAuthn/passkey support:
166-
167-
```bash
168-
PASSKEY_RP_ID=yourdomain.com
169-
PASSKEY_RP_NAME=OpenCode Manager
170-
PASSKEY_ORIGIN=https://yourdomain.com
171-
```
172-
173-
### Push Notifications (VAPID)
174-
175-
Enable push notifications for the PWA (background alerts for agent questions, permission requests, errors, and session completions):
70+
# Pre-configured admin (optional)
71+
ADMIN_EMAIL=admin@example.com
72+
ADMIN_PASSWORD=your-secure-password
17673

177-
```bash
178-
# Generate keys: npx web-push generate-vapid-keys
179-
VAPID_PUBLIC_KEY=your-public-key
180-
VAPID_PRIVATE_KEY=your-private-key
181-
VAPID_SUBJECT=mailto:you@yourdomain.com
74+
# For LAN/remote access
75+
AUTH_TRUSTED_ORIGINS=http://localhost:5003,https://yourl33tdomain.com
76+
AUTH_SECURE_COOKIES=false # Set to true when using HTTPS
18277
```
18378

184-
**Important**: `VAPID_SUBJECT` MUST use `mailto:` format for iOS/Safari push notifications to work. Apple's push service rejects `https://` subjects.
185-
186-
### Dev Server Ports
187-
188-
The Docker container exposes ports `5100-5103` for running dev servers inside repositories:
189-
190-
```bash
191-
# Example: Vite
192-
server: { port: 5100, host: '0.0.0.0' }
193-
194-
# Access at http://localhost:5100
195-
```
79+
For OAuth, Passkeys, Push Notifications (VAPID), and advanced configuration, see the [Configuration Guide](https://chriswritescode-dev.github.io/opencode-manager/configuration/environment/).
19680

19781
## Documentation
19882

199-
For detailed guides and configuration reference, see the **[Documentation Site](https://chriswritescode-dev.github.io/opencode-manager)**.
200-
201-
- [Getting Started](https://chriswritescode-dev.github.io/opencode-manager/getting-started/installation/) - Installation and first-run setup
202-
- [Features](https://chriswritescode-dev.github.io/opencode-manager/features/overview/) - Deep dive on all features
203-
- [Configuration](https://chriswritescode-dev.github.io/opencode-manager/configuration/environment/) - Environment variables and advanced setup
204-
- [Troubleshooting](https://chriswritescode-dev.github.io/opencode-manager/troubleshooting/) - Common issues and solutions
205-
- [Development](https://chriswritescode-dev.github.io/opencode-manager/development/setup/) - Contributing and local development
206-
83+
- [Getting Started](https://chriswritescode-dev.github.io/opencode-manager/getting-started/installation/) — Installation and first-run setup
84+
- [Features](https://chriswritescode-dev.github.io/opencode-manager/features/overview/) — Deep dive on all features
85+
- [Configuration](https://chriswritescode-dev.github.io/opencode-manager/configuration/environment/) — Environment variables and advanced setup
86+
- [Troubleshooting](https://chriswritescode-dev.github.io/opencode-manager/troubleshooting/) — Common issues and solutions
87+
- [Development](https://chriswritescode-dev.github.io/opencode-manager/development/setup/) — Contributing and local development
20788

20889
## License
20990

0 commit comments

Comments
 (0)