Skip to content

Latest commit

 

History

History
119 lines (98 loc) · 6.59 KB

AGENTS.md

File metadata and controls

119 lines (98 loc) · 6.59 KB

Repository Guidelines

Repository Scope

  • Jcode Desktop is in a separate repository.

TUI style

  • 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.

Development Workflow

  • 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.name and user.email. Do not override them with Jcode, 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.md for the contribution policy.
  • Prefer master/main - Work directly on the repository's primary branch (master or main) 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.

Provider model discovery

  • 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.

Install Notes

  • ~/.local/bin/jcode is the launcher symlink used from PATH.
  • ~/.jcode/builds/current/jcode is the active local/source-build channel; self-dev builds and scripts/install_release.sh point the launcher here.
  • ~/.jcode/builds/stable/jcode is the stable release channel; scripts/install.sh installs this and points the launcher here.
  • ~/.jcode/builds/versions/<version>/jcode stores immutable binaries.
  • ~/.jcode/builds/canary/jcode still exists for canary/testing flows, but it is not the primary self-dev install path.
  • On Windows, the equivalents are %LOCALAPPDATA%\\jcode\\bin\\jcode.exe for the launcher, %LOCALAPPDATA%\\jcode\\builds\\stable\\jcode.exe for stable, and %LOCALAPPDATA%\\jcode\\builds\\versions\\<version>\\jcode.exe for immutable installs; scripts/install.ps1 currently installs the stable channel.
  • Ensure ~/.local/bin is before ~/.cargo/bin in PATH.

Verifying a change at runtime

Keep benchmark sessions out of user history

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::info writes to a log file, not stderr, so instrumenting a code path with it produces no visible output under --trace. Use eprintln! for throwaway diagnostics and delete it before committing.
  • Confirm which binary you are actually inspecting. strings on builds/shared-server/jcode reads a 70-byte symlink, not a program; resolve it with readlink -f first.

Fork footprint (camerontaylor/jcode)

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/*.json by 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.