Using tallow in existing Claude Code projects

tallow is designed to run in projects that already use Claude Code conventions. In most cases, you can start tallow and keep using your existing .claude/ layout. This guide is about compatibility first, migration second.

What works without rewriting files

Claude Code resource	Works in tallow	Notes
CLAUDE.md	✅	Loaded by pi/context-files. Works at root, ancestors, and nested directories.
.claude/commands/	✅	Loaded by command-prompt (project root + user home).
.claude/skills/	✅	Loaded via claude-bridge + skill-commands.
.claude/agents/	✅	Loaded by subagent-tool, agent-commands-tool, and context-fork.
.claude/rules/*.md	✅	Loaded by context-files (root and nested .claude/rules/).
Name collision behavior	✅	.tallow/ wins over .claude/ for commands/skills/agents with the same name.

AGENTS.md vs CLAUDE.md

Both can coexist.

• pi prefers AGENTS.md when both exist in one directory.
• context-files then adds the skipped file so both end up in context.
• For subdirectories, context-files discovers both files directly.

Practical result: keep CLAUDE.md for Claude Code, add AGENTS.md for tallow, run both tools in the same repo.

Frontmatter compatibility (important corrections)

Claude Code’s official skill frontmatter includes fields like: allowed-tools, context, agent, model, hooks, disable-model-invocation, and user-invocable.

So to be explicit: allowed-tools and context: fork are not tallow-only ideas. They are first-class Claude Code features.

Where behavior diverges in tallow today:

• context: fork is supported in tallow’s forked-execution flow.
• allowed-tools is parsed in tallow fork metadata, but is currently not enforced there as a permission gate.
• Claude’s hooks frontmatter on skills/agents is a Claude feature; tallow’s hook system is configured via hook files/settings (see below).

If you want cross-tool files to behave the same, keep shared frontmatter minimal and test the behavior in both CLIs.

Hooks: compatible shape, different event keys

If you already use Claude hooks, the overall structure carries over well (matcher, hooks, type, command), but event keys are not 1:1.

tallow does not currently auto-translate Claude hook event names such as PreToolUse, PostToolUse, or Stop.

Use tallow event keys directly:

Claude Code event	Closest tallow hook event
SessionStart	session_start
UserPromptSubmit	input
PreToolUse	tool_call
PostToolUse	tool_result
SubagentStart	subagent_start
SubagentStop	subagent_stop
Notification	notification
TeammateIdle	teammate_idle
TaskCompleted	task_completed
PreCompact	session_before_compact / session_compact
SessionEnd	session_shutdown
Stop	agent_end (closest, not identical semantics)

Known gaps vs Claude hook events:

• No dedicated PermissionRequest hook event in tallow.
• No dedicated PostToolUseFailure event (use tool_result and inspect error state).
• .claude/settings.json hook sections are not auto-imported into tallow hooks.

See hooks for tallow’s native event list.

Nested directory behavior (important)

Compatibility is not identical for every resource type.

Resource	Nested subdirectory support
CLAUDE.md / AGENTS.md	✅ yes
.claude/rules/	✅ yes
.claude/commands/	⚠️ project root + user home locations (not arbitrary nested .claude/commands/)
.claude/skills/	⚠️ project root + user home locations
.claude/agents/	⚠️ project root + user home locations

Compatibility gaps to keep in mind

• Hook event name mapping is manual (see section above).
• MCP server config is read from .tallow/settings.json / ~/.tallow/settings.json (mcpServers), not from Claude-specific config files.
• Some advanced tallow frontmatter is intentionally tallow-only.

Optional migration (not required)

You can keep .claude/ permanently and still use tallow.

If you want a tallow-native layout later, run /init and adopt .tallow/ incrementally. Compatibility does not depend on doing this.