mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-03 14:09:42 +02:00
Codeman maintainer
f3cb7696f0
30 pages covering install, concepts, the dashboard, the agent CLIs, unattended
runs, remote and Docker cases, security and the HTTP API, plus a sidebar and a
footer. The wiki repo has no CI and no review, so docs/wiki is the source of
truth and .github/workflows/wiki-sync.yml mirrors it on every push to master.
The workflow refuses to mirror when docs/wiki is missing or holds no pages,
because it deletes before it copies and would otherwise publish the deletion of
every page. The footer carries a {{VERSION}} placeholder stamped at publish
time rather than a hand-written version, which went stale on every release.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
119 lines
5.5 KiB
Markdown
119 lines
5.5 KiB
Markdown
# 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. Six of the seven 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).
|