diff --git a/README.md b/README.md
index 39e892e..3bba44d 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,34 @@ ln ~/.gitconfig ~/.local/share/agent-container/container-home/.gitconfig
 
 Avoid linking sensitive files such as `~/.ssh/id_*` or `~/.gnupg/` -- keeping those out of the container is an intentional security boundary.
 
+## Sharing agent state between host and container via symlinks
+
+State directories such as `.claude/`, `.pi/`, or `.agents/` can be shared between the
+containerized tools (`claude`, `pi`, `opencode`) and their local variants
+(`claude-local`, `pi-local`, `opencode-local`). Keep the real data in the container home
+and symlink to it from your real `$HOME`:
+
+```sh
+mkdir -p ~/.local/share/agent-container/container-home
+mv ~/.claude ~/.local/share/agent-container/container-home/.claude
+ln -s ~/.local/share/agent-container/container-home/.claude ~/.claude
+```
+
+The direction matters: the real directory must live in the container home, and the
+symlink must be in the host `$HOME`. The container mounts the container home as
+`/home/<username>`, so inside the container the path is a regular directory. The host
+`$HOME` is never mounted into the container, so a symlink pointing the other way would
+not resolve inside the container.
+
+On the host, `~/.claude` resolves to the same data the container sees, so logins,
+settings, and history are shared by both sides without copying or syncing. The same
+works for single files like `.claude.json` if a tool needs them on the host too.
+Repeat the two steps for other state directories (`.pi`, `.agents`,
+`.config/opencode`, ...) as needed.
+
+If `XDG_DATA_HOME` is set to a non-default location, use that path instead. As with
+hard links, never share sensitive files such as `~/.ssh/id_*` or `~/.gnupg/`.
+
 ## OpenCode plugins
 
 The repository ships an OpenCode plugin in `plugins/opencode/`: