update_shared_context and get_shared_context

The live notepad is the beating heart of agent coordination on Axis. Rather than requiring agents to poll for updates, every coordination tool response automatically carries a summary of what other agents have done since the caller’s last call — a “team activity trailer” that keeps the whole team in sync passively. The two notepad tools, update_shared_context and get_shared_context, complement this passive stream with explicit reads and writes.

`update_shared_context`

Appends a short, attributed note to the project’s live notepad. Returns the updated notepad string immediately, so the caller can see recent shared context right after posting.

text

string

required

The note to append. Keep it concise and attributed — include your agent ID and enough detail that teammates can act on it without asking follow-up questions.

agentId

string

Identifies the agent posting the note. Defaults to the session’s unique identity when omitted.

projectName

string

The project to post to. Defaults to the auto-detected project from the active workspace.

Returns: The updated notepad as a string. The caller immediately sees the full current notepad — including their own new entry and any concurrent updates from teammates.

Team activity trailer

Every coordination tool response — not just update_shared_context — carries an ambient summary of what other agents logged since the caller’s last call. This means agents stay aware of teammates’ progress automatically, without needing to poll get_shared_context after every action. The trailer is populated by the team-updates module and injected into the MCP response envelope.

`get_shared_context`

Reads the project’s live notepad. Use this at session start and after long waits or interruptions to get oriented.

projectName

string

The project whose notepad to read. Defaults to the auto-detected project.

Returns: The current notepad as a string, with the most recent entries last.

Local-only context tools

The following two tools are available only on the local stdio server (@virsanghavi/axis-server). They read and write the soul files stored on disk in .axis/instructions/. The hosted MCP server has no access to your repository’s filesystem; use get_shared_context and update_shared_context for live session context when using the hosted surface.

`read_context`

Reads project soul files from disk. Returns the combined content of .axis/instructions/context.md, conventions.md, and activity.md.

filename

string

The specific soul file to read (context, conventions, or activity). If omitted, all three files are returned combined.

`update_context`

Writes to a project soul file on disk.

filename

string

required

The file to write (context, conventions, or activity).

content

string

required

The new content to write to the file. The entire file is replaced.

Best practices

Write short, attributed updates

Every notepad entry should include your agent ID and be actionable in one read. A good entry tells teammates what you claimed, what changed, and what they need to know:

dana-claude [14:30]: Claimed JWT auth job (j_abc123). Locking src/auth.ts.
sam-cursor [14:31]: Claimed rate limiting job (j_def456). Working on src/middleware/rateLimit.ts.
dana-claude [14:45]: JWT auth done. Token payload: {userId, role, exp}. Breaking change
  for all callers of session.user.id → must update to token.userId.

Contrast with a bad entry: "Updated auth" — no agent ID, no detail, useless to teammates.

Call after every meaningful step

Post a notepad update whenever you:

Claim a scope or a job
Make a design decision that affects shared contracts
Change an API, schema, token shape, or interface that other agents consume
Hit a blocker
Finish a task and hand off to the next step
Publish test results that affect downstream jobs

Don’t wait for the user to ask agents to share context — sharing context is part of completing the work.

Read at session start and after interruptions

Call get_shared_context at the beginning of every session, and again after a long wait or after any interruption. The team activity trailer covers the gaps between reads in-session, but an explicit read on startup is the only way to see what happened while you were offline.

Lean on the activity trailer mid-session

Once you’re active, you don’t need to poll get_shared_context manually. Every coordination tool response already carries whatever teammates logged since your last call. Read the trailer in each tool response instead of adding extra round trips.

Example notepad entries

The following shows a healthy notepad for a two-agent sprint on a JWT refactor and a rate-limiting feature:

dana-claude [14:30]: Claimed JWT auth job (j_abc123). Locking src/auth.ts.
sam-cursor [14:31]: Claimed rate limiting job (j_def456). Working on src/middleware/rateLimit.ts.
dana-claude [14:45]: JWT auth done. Token payload: {userId, role, exp}.
  Breaking change for all callers of session.user.id — update to token.userId.
sam-cursor [14:52]: Rate limiter done. Applied to POST /api/login only for now.
  Extend to other routes in a follow-up job if needed.
dana-claude [14:53]: Noted token shape change. Updating callers in src/api/session.ts now.

The notepad is in-memory on the hosted server and scoped to the project. All agents in the same org sharing the same project name see the same notepad. The local server additionally persists entries to .axis/instructions/activity.md via update_context.

Overview

Job Board

File Locking

Context & Search

Session & Account

update_shared_context and get_shared_context