BitSquare/Codeman
2
0
Fork 0
mirror of https://github.com/Ark0N/Codeman.git synced 2026-10-03 14:09:42 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
47f209bf0a7b4a9fcd2c027c19077b49c82fb166
Codeman/docs/wiki/Contributing.md
T
Codeman maintainer bd286bf502 docs(wiki): catch the manual up to 1.29.0 and add the three run modes it never had 
The wiki was written for seven run modes and never received Grok Build, DeepSeek
Harness or OMP. They now appear everywhere the others do: the modes table and
per-CLI notes, install commands, environment prefixes, the Quick Start table, the
requirements rows, the vocabulary, and every "seven modes" count.

The 1.27 to 1.29.0 changes land on the pages that own them: attaching a case to an
existing container, multi-case adoption and the copy-a-case picker (Docker Cases);
file reads over ssh in remote cases and what stays unavailable (Remote SSH Sessions,
Working With Files, Security); single-page app routing, frame recovery, localhost
links as tabs and the egress guard (Web Tabs); DeepSeek as the one non-Claude mode
with real stop/blocked signals and Approvals items, Codex's own work detection,
last-response, the model-endpoint routes and refreshed counts (HTTP API, Driving
From An Agent, Hooks, Notifications, Keeping Agents Running, Core Concepts);
Shift+drag, right-click copy, Auto Copy, the Ctrl+Z guard, font weight, the vertical
rail and its activity sort (Keyboard Shortcuts, Input And Voice, The Dashboard,
Settings Reference); the 600px phone cutoff, Codex shift arrows and iPhone Duo
(Mobile Guide); the Docker Compose route and its update rule (Installation, Running
As A Service); four new symptom entries and a "which CLIs" question (Troubleshooting,
FAQ).

Custom model endpoints are deliberately left to #430, which adds that page and edits
Agent CLIs, Settings Reference and the sidebar; these edits stay out of the regions
#430, #428 and #376 touch, and all three still merge cleanly on top.

Both READMEs: the web-tab menu entry is labelled "Add URL" in the UI, not
"Add dashboard".

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-15 19:05:59 +02:00

119 lines
5.5 KiB
Markdown
Raw Blame History

# Contributing
The full guide lives in
[CONTRIBUTING.md](https://github.com/Ark0N/Codeman/blob/master/.github/CONTRIBUTING.md).
This page is the short orientation, plus how to fix a page in this wiki.
## Where things go
| You have | Send it to |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| A bug | An [issue](https://github.com/Ark0N/Codeman/issues), with OS, install method, browser, and which CLI the session was running. |
| A question or setup problem | [Discussions](https://github.com/Ark0N/Codeman/discussions). |
| An idea | [Ideas](https://github.com/Ark0N/Codeman/discussions/categories/ideas), where it gets voted on. |
| A small fix | Straight to a PR. |
| A bigger feature | An issue or Discussion first, then build once the design has a nod. |
| A security problem | Never a public issue. See [SECURITY.md](https://github.com/Ark0N/Codeman/blob/master/.github/SECURITY.md). |
Issues usually get a response within a day, and every release credits its contributors and
bug reporters by name.
## Dev setup
```bash
git clone https://github.com/Ark0N/Codeman.git
cd Codeman
npm install # postinstall builds the vendored xterm addon bundles
npm run dev # http://localhost:3000
```
Requirements: Node 22+, tmux, and at least one agent CLI on your PATH.
The frontend is plain JavaScript with no bundler in dev: edit a `.js` or `.css` file and
reload. The exception is `index.html`, which is read once at server start, so markup changes
need a restart.
## Before you push
CI runs all of these, so running them locally saves a round trip:
```bash
npm run typecheck
npm run lint
npm run format:check
npm run check:frontend-syntax
npm test -- test/<file>.test.ts # one file, the normal way
npm run test:ci # the full CI sweep
```
**Never run bare `npm test`.** The default configuration includes browser-driven Playwright
suites that need a live server, Chromium, and environment-specific baselines; they hang or
fail on a normal machine. `test:ci` is the honest "run everything".
Tests are tmux-safe by design: under vitest the tmux layer becomes an in-memory mock, so
tests cannot touch real sessions. If you add a test that binds a port, pick a unique one at
3150 or above, and never 3000.
## Finding your way around
- Every source file opens with a `@fileoverview` block. Read it before the file; it is the
map.
- [`CLAUDE.md`](https://github.com/Ark0N/Codeman/blob/master/CLAUDE.md) at the repo root is
the densest architecture primer there is. It is written for AI coding agents, but its
invariants apply identically to humans, and most review feedback traces back to something
already written there.
- [`docs/architecture-invariants.md`](https://github.com/Ark0N/Codeman/blob/master/docs/architecture-invariants.md)
holds the deep mechanisms and the history behind each rule.
## Good first contributions
- **A theme skin.** A skin is four things kept in sync, and a static test checks the sync, so
if the test passes your skin works.
- **A language.** The i18n module is dependency-free, English is canonical, and Simplified
Chinese is a complete example to copy.
- **Docs.** If you got stuck and then figured it out, the sentence that would have unstuck
you is a pull request.
- Anything labelled
[good first issue](https://github.com/Ark0N/Codeman/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
Worth discussing first: new CLI backends, and real-device testing reports, especially
mobile, which always find things emulation cannot.
## PR expectations
- One change per PR. Small and focused reviews fast; a grab bag stalls.
- Target `master`.
- **Keep your branch mergeable.** A PR with conflicts silently gets no CI runs at all, which
is a GitHub quirk rather than a Codeman one. Rebase when conflicts appear.
- Include or update tests when you change behaviour.
- Do not bump versions or edit the changelog; releases are handled after merge.
- AI-assisted contributions are welcome, with one condition: understand what you are
submitting, and actually run it. "The model said it works" is not a test.
## Fixing this wiki
These pages are generated from
[`docs/wiki/`](https://github.com/Ark0N/Codeman/tree/master/docs/wiki) in the main
repository, and pushed here automatically when master changes.
**Editing a page in the browser will be overwritten by the next sync.** Send a pull request
against `docs/wiki/` instead. It is plain markdown, and a documentation PR is a genuinely
useful contribution.
Conventions for wiki pages:
- Links between pages use the wiki form: `[Remote Access](Remote-Access)`, no `.md`.
- Links into the repository are absolute `https://github.com/Ark0N/Codeman/blob/master/...`
URLs.
- Images are referenced from the main repository over raw URLs rather than being copied into
the wiki.
- Say what the default is, especially when it is off. Most of Codeman is opt-in.
- Label Claude-only behaviour every time it appears. Nine of the ten run modes are not
Claude.
## Conduct
Be kind, be direct, assume good faith. Report unacceptable behaviour privately via the
contact in
[SECURITY.md](https://github.com/Ark0N/Codeman/blob/master/.github/SECURITY.md).
Reference in New Issue View Git Blame Copy Permalink