Skip to content
palmpalmpalm

Monorepos (coming in 0.3)

palm 0.2 treats a monorepo as one project, with one palm.yaml at the repository root. Every entry installs at the root, and every package sees it. Placing an instruction in one package arrives in palm 0.3.

Terminal window
cd ~/work/carbon
palm install acme/agent-kit db-conventions --at packages/database

palm 0.2 stores at: packages/database in palm.yaml and in the lock, installs at the root for now, and says so.

i at packages/database (placed at the root until 0.3)

When you upgrade to 0.3, the next palm install moves the entry into the package without an edit to palm.yaml.

What works in 0.2

Section titled “What works in 0.2”
  • One root palm.yaml, committed, with the targets and sources for the whole repository.
  • Project discovery stops at the nearest .git, so a palm.yaml in another repository above yours is never used.
  • palm init inside a package refuses when a palm.yaml sits above it in the same repository, and names both ways forward.
x packages/jobs is inside project /work/carbon (palm.yaml). Add entries with --at packages/jobs, or start a separate project here: palm init --here

palm init --here makes the package a project of its own. Use it only for a package that should not share the root setup, because two projects in one repository install and check separately. A nested project may still use an in-repo source anywhere in the same git worktree, such as the root’s kit as ../../agent-kit. palm get targets and palm describe target print the project root, so you always see which palm.yaml a command used.

Narrow package rules per entry

Section titled “Narrow package rules per entry”

Until at: works, per-entry targets: is the 0.2 tool for a rule that one package needs. Codex reads every instruction from the root AGENTS.md, for every package. Claude Code and Cursor read rule files that carry path globs, so a globbed rule loads only for that package’s files.

palm.yaml
targets: [claude, codex, cursor]


sources:
  acme/agent-kit:
    ref: ^1.0
    instructions:
      - { name: db-conventions, targets: [claude, cursor], at: packages/database }

palm install acme/agent-kit db-conventions --targets claude,cursor --at packages/database writes the same entry. The rule then stays out of the root AGENTS.md, which palm keeps below the size at which Codex stops reading.

What 0.3 adds

Section titled “What 0.3 adds”
Feature What it does
at: <dir> honoured The entry’s placement root: nested AGENTS.md and GEMINI.md blocks, <dir>/.cursor/rules, <dir>/.agents/skills, globs rebased. Claude Code keeps root rules with paths:.
Derived placement An instruction whose paths share one directory gets that directory as at:, and palm prints it.
One carrier per harness An entity reaches each harness through exactly one file, so Cursor never loads a rule from both AGENTS.md and .cursor/rules.
Version check across projects palm check warns when one entity is installed at two versions in nested projects or scopes.

Until then, keep package-specific rules small, or narrow them as above, so the root AGENTS.md stays under 24 KiB. Above that, palm install and palm check warn. Above Codex’s cap, the install refuses without --force, and the hint names targets:. Nested projects install and check one at a time; a palm check --recursive over every palm.yaml in the worktree is a candidate for 0.3.

Section titled “Related”