- Jcode Desktop is in a separate repository.
- UI chrome must not wrap: startup headers, account rows, status labels, and other compact UI rows should fit their available terminal-cell width or truncate with an ellipsis. Count Unicode display cells, not characters. Preserve one logical row per visual row, including at narrow widths. Chat prose and other intentionally multiline content may wrap normally.
- Reuse the info widget's limit-bar renderer for usage indicators instead of introducing a different bar glyph, color, or used/remaining convention.
- Commit and push as you go - Make small, scoped commits and push them to the current branch's remote as meaningful work is completed, rather than waiting until the end of the task. Preserve unrelated changes and never force-push unless the user explicitly authorizes it.
- Use the user's Git identity - Create commits with the configured
user.nameanduser.email. Do not override them withJcode,Jcode agent, or a fabricated agent email. Preserve existing contributor attribution when integrating work. If no identity is configured, ask rather than inventing one. - Welcome pull requests from everyone - Review contributions on their merits,
regardless of whether the author is a maintainer, an existing contributor, a
first-time contributor, or an agent. Good PRs can be merged directly after review
and validation. Do not require a maintainer-authored rewrite merely because of
who submitted the change. See
CONTRIBUTING.mdfor the contribution policy. - Prefer master/main - Work directly on the repository's primary branch
(
masterormain) by default. Do not create a branch or worktree merely to start a task. Only do so when the user explicitly requests it or isolation is genuinely necessary, and explain the concrete reason first. - Keep work scoped - Preserve unrelated work. If already on a branch with ongoing changes, finish and integrate safely rather than switching blindly. When the user asks you to review or integrate a PR or branch, you may inspect, test, and integrate that contribution regardless of author status. Do not pull in unrelated branches or merge a PR without user authorization.
- Model arrays are offline fallbacks, not release allowlists. Providers with a catalog must discover new model IDs without a Jcode release and expose them through switching lists and structured model routes.
- Implement both cached prefetch and explicit refresh. Explicit refresh must bypass fresh caches. Preserve the last good catalog on network, authentication, or malformed-response failures, and scope persistent caches to their endpoint.
- Wire new providers into the shared refresh fanout and model-update publication, including long-lived sessions, not only startup or login.
- Regression tests must discover an arbitrary future model absent from all fallback arrays, using the provider's actual response schema. Check picker routes, forced refresh with a fresh cache, and last-good behavior on failure.
- If a backend has no discovery API, document that limitation instead of presenting a hardcoded list or a no-op refresh as live discovery.
~/.local/bin/jcodeis the launcher symlink used fromPATH.~/.jcode/builds/current/jcodeis the active local/source-build channel; self-dev builds andscripts/install_release.shpoint the launcher here.~/.jcode/builds/stable/jcodeis the stable release channel;scripts/install.shinstalls this and points the launcher here.~/.jcode/builds/versions/<version>/jcodestores immutable binaries.~/.jcode/builds/canary/jcodestill exists for canary/testing flows, but it is not the primary self-dev install path.- On Windows, the equivalents are
%LOCALAPPDATA%\\jcode\\bin\\jcode.exefor the launcher,%LOCALAPPDATA%\\jcode\\builds\\stable\\jcode.exefor stable, and%LOCALAPPDATA%\\jcode\\builds\\versions\\<version>\\jcode.exefor immutable installs;scripts/install.ps1currently installs the stable channel. - Ensure
~/.local/binis before~/.cargo/bininPATH.
For synthetic prompts and streaming/CPU/power benchmarks, set a dedicated
JCODE_HOME and JCODE_TEST_SESSION=1 for both the server and its clients,
in addition to using a unique --socket. A private socket alone isolates the
daemon, not persisted sessions. Never run synthetic benchmark prompts against
the user's normal session storage.
cargo build alone proves nothing about behavior. jcode run and interactive
sessions are served by the long-lived daemon at
~/.jcode/builds/shared-server/jcode, which is a symlink into
~/.jcode/builds/versions/<version>/. Until that symlink is repointed and the
daemon restarted (jcode self-dev --build), a freshly built binary is inert and
every runtime check silently measures the old code.
To test a change without disturbing the shared daemon or the caller's session, run your build against its own socket:
cargo build --profile selfdev
./target/selfdev/jcode run --no-update --socket /run/user/1000/jcode-mytest.sock '<prompt>'Two things that waste time otherwise:
crate::logging::infowrites to a log file, not stderr, so instrumenting a code path with it produces no visible output under--trace. Useeprintln!for throwaway diagnostics and delete it before committing.- Confirm which binary you are actually inspecting.
stringsonbuilds/shared-server/jcodereads a 70-byte symlink, not a program; resolve it withreadlink -ffirst.
This fork carries its changes against a fast-moving upstream, so every hunk
in upstream-owned code is a recurring conflict. When a change crosses the
daemon protocol boundary (crates/jcode-protocol, crates/jcode-app-core,
crates/jcode-base, crates/jcode-tui), minimise the footprint there instead
of improving the architecture:
- Add the smallest in-place hook: a field, an enum variant at the end of its
list, or a call into a new fork-owned file. Put the logic in that new file
or under
src/cli/acp/. - Do not move, split, rename or refactor upstream code, even when the result would be cleaner.
- The size ratchets do not override this. If a hook pushes an upstream file
over a fork budget, raise that file's entry in
scripts/fork/*.jsonby the hook's size and say so in the commit message. Those budgets are fork-owned; moving upstream code is not.
Rules and rationale: docs/FORK_BOUNDARY_STRATEGY.md.