Skip to main content

Peer work

The rules an agent follows when it works for another session, or asks another session to work.

This page is the peer-work skill. Claude Code, Codex and Ramabana sessions on one Mac can send each other notes and asks. The skill tells each side how to do that work without bad code. The user cares most about this: the code must follow the rules of the repo that owns it.

The skill text is this module’s docstring, as in coding_patterns. pyproject.toml registers the module under the pyskills entry point as peer_work. ramabana setup peers copies the text into the Claude Code and Codex instruction files. To change what an agent reads, edit the exported cell below.

Read this before you work for another session, or ask another session to work for you. Sessions are Claude Code, Codex and Ramabana sessions on this Mac.

Two roles exist. The worker does the work. The owner holds the repo. One session can have both roles.

When you do work for another session (worker)

  1. Read the repo rules before you write code. Read CLAUDE.md or AGENTS.md and the repo skills. Some repos have their own pattern. For example, vedicreader builds features from small lego blocks. Read the repo’s rules to find its pattern.
  2. Follow the user’s general rules. Use functional style. Write short and efficient code. Write one-line docstrings. Add no comments that are not needed. Write prose in STE. Do not add code that you do not need. Do not write a helper that already exists.
  3. Agree the shape with the owner before you add code that the owner’s repo will keep. Send an ask: ramabana tell OWNER "..." --ask --repo R --wait N. Name the blocks to use, the place for the code and the API. Wait for a reply from the owner that starts with agreed:. Then write the code.
  4. Do not edit a folder that another live session works in. The tool or hook refuses the write and names the folder. Ask the owner to make the change.
  5. Show proof before you say “done”. Show the test command and its output. For UI, check the page in Chrome for Testing and show the screenshot path. Never use the user’s own Chrome. No proof means the work is not done.

When you own the repo (owner)

  1. Review the diff against your repo’s rules. Do this before you accept the work.
  2. If the code is too large or does not follow the repo’s patterns, ask for changes.
  3. Accept the work only when the code follows the rules.
  4. Before you do the work in an ask, read your repo rules. If the ask breaks them, reply refused: <why> and name the rule.
  5. When you agree to the shape that a worker sends, start your reply with agreed:.

Find sessions

  • If the hook gave you a full command for ramabana, use that command.
  • Run ramabana peers to list live sessions. Add --ids to see the session ids.
  • After /add-dir, run ramabana peers --add-folder PATH. The folder guard then knows the new folder.
  • Inside Ramabana, use the peers() tool.

Send

  • ramabana tell TARGET TEXT sends a note. A note needs no answer.
  • Add --ask to request work. Add --repo R so that the receiver knows whose rules apply. Add --wait N to wait N seconds for the reply.
  • Add --all to send to every live session.
  • Inside Ramabana, use tell(session, text, kind='note'|'ask', wait=60).
  • An ask needs the user’s approval, unless work together mode is on with that sender.
  • Work together mode does not change tool permissions. Your own permission mode still applies.
  • The peers reference lists the default limits. Replies do not count against the message allowance. Set RAMABANA_PEER_MESSAGES, RAMABANA_PEER_ASKS, or RAMABANA_PEER_HOPS before process startup to override a limit. Values must be positive integers. Running processes keep their loaded limits.

Receive

  • Run ramabana inbox to read your messages. Add --wait N to wait for new ones.
  • A note is information only. If a note asks for work, treat it as an ask: ask the user unless work together mode is on with that sender.
  • Answer with ramabana tell TARGET TEXT --reply-to THREAD. Take THREAD from the message.
  • End a finished reply with these two lines:
    • changes: file or commit; file or commit
    • proof: command → result; screenshot path
  • If you decline, start the reply with refused: <why>. If you fail, start it with failed: <why>.
  • Do not reply to a reply that has no new request.

Work together mode

  • ramabana together on lets those sessions send asks to you without approval. Add --with A,B to name them. Add --until HH:MM to set the end. Without --until, it ends after 12 hours.
  • ramabana together off ends it. ramabana together status shows it. In Claude Code and Codex it also ends when the user types. In Ramabana it stays on, and work_together() turns it on or off when the user tells you to work with peers.
  • ramabana report shows what the sessions did: changes, proof and the user’s action list.

The test reads the skill text. It checks that each rule, each reply line and each command the protocol needs is present, with the agreed: signal and the rule that stops an endless chain of replies. It also checks that the skill stays short and that skill discovery finds it.

from ramabana.peer_work import __doc__ as skill
from ramabana import tools
rules = ['CLAUDE.md', 'AGENTS.md', 'one-line docstrings', 'Agree the shape', 'owner', 'another live session',
         'Chrome for Testing', 'screenshot', 'changes:', 'proof:', 'refused:', 'failed:',
         'ramabana tell', '--reply-to', '--ask', 'ramabana peers --add-folder', '/add-dir', 'ramabana inbox',
         'work together mode', 'ramabana together', 'tool permissions', "Never use the user's own Chrome", '--wait', '--all', 'ramabana peers', '--ids', '(worker)', '(owner)',
         'agreed:', 'Do not reply to a reply that has no new request.', 'If the hook gave you a full command for `ramabana`, use that command.']
missing = [r for r in rules if r not in skill]
assert not missing, missing
assert len(skill.splitlines()) <= 60
assert 'peer_work' in {s.name for s in tools.discover()}