Claude Code Best Practices: CLAUDE.md, tmux, Telegram, and Email

Claude Code does more than write code. With the right structure around it, it can operate as a business operating system - handling client work, content, deployments, SEO, strategic decisions, all of it running across multiple projects at the same time.

The structure that’s working right now is CLAUDE.md files, tmux for session persistence, Telegram and email as communication bridges, and isolated client workspaces. This is still evolving. Some of this might look different in six months. But here’s where things stand.

CLAUDE.md files are the architecture

Every Claude Code session reads CLAUDE.md files automatically when it starts. These files define everything - coding standards, business context, voice and tone, operational constraints, credentials, project status, behavioural rules. They shape how Claude Code approaches work for that specific context.

The setup that’s working has CLAUDE.md files at two levels, plus agent instruction files:

The home directory file (~/CLAUDE.md) covers identity, communication preferences, network topology, and mechanical overrides. It loads into every session regardless of which client directory is active. Client-level files sit inside each client’s working directory and cover their specific tech stack, deployment targets, current priorities, brand voice, and content strategy. Then there are agent-level instruction files that define specialists - an SEO agent, a blog writer, a voice agent, a strategy agent, an ops procedures agent. Each one is a markdown file. Load it into a session and Claude Code takes on that role.

The multi-agent system is markdown files in a folder. The “routing” is just choosing which agent to load, or telling Claude Code to pick one based on the task.

The thing that seems to matter most with CLAUDE.md files is specificity. A vague instruction like “write good content” produces generic output. Something like “never start a sentence with ‘In my experience’ and never centre the writer as the protagonist of a client story” actually produces enforceable results. The more precise the constraint, the more reliable the output. We’ve been treating these files more like code than documentation - versioning them, iterating on them, tightening the language over time. Whether that’s the right mental model or just how it’s shaken out, it’s working.

Why does tmux matter for Claude Code?

Claude Code sessions die when the terminal closes. tmux keeps them alive. That’s basically the whole reason.

A machine running tmux maintains persistent sessions for every active client, each with its own working directory and CLAUDE.md context. Detach, reattach from anywhere, pick up where things left off. One tmux session per client, named clearly (tmux new -s client-name), running on a machine that stays on - a Mac Mini, a cloud server, whatever. The point is persistence.

What this means in practice is parallel execution across completely isolated workspaces. Client A’s SEO audit runs while Client B’s deployment happens while Client C’s content gets written. No context bleeding. Each session only sees its own files.

How do Claude Code sub-agents work?

Claude Code has a built-in Agent tool that handles parallelisation on its own. When a task involves multiple independent files, Claude Code can spawn sub-agents to work on them simultaneously instead of going through them one by one.

This doesn’t need manual orchestration. Claude Code figures out which files are independent, launches parallel workers, and gets through the work faster than sequential processing would. A CLAUDE.md instruction can push it to parallelise more aggressively:

For tasks touching more than 5 independent files, you MUST launch parallel sub-agents (5-8 files per agent). Not optional.

Without that kind of override, Claude Code tends to play it safe and process things sequentially. The override is a way of saying “these files don’t depend on each other, go parallel.”

Sub-agents are useful for multi-file refactors, running verification passes while other work continues, content generation across multiple pages, and parallel research tasks. The main limitation is that sub-agents don’t share state cleanly, so anything where task B depends on task A’s output needs to stay sequential. But most real work has more independence than it first looks like. An agentic AI system that parallelises well gets through a lot more in the same time.

The Telegram bridge: Claude Code without a terminal

About 200 lines of Python. A Telegram bot listens for messages, pipes them to Claude Code as a subprocess, and sends responses back.

What it actually changes is access. Instructions go in from a phone. Approvals happen from a phone. The agents execute while the human handles judgment calls from wherever. It sounds simple because it is simple, but it meaningfully changes how much gets delegated because the friction of “open a terminal” disappears.

An example: send “audit the SEO on the advisory page” from a phone. Claude Code loads the SEO agent instructions, runs the audit, reports findings via Telegram. Approve fixes from the phone. Claude Code executes, runs verification, reports completion. A laptop never opened.

Building the bridge takes an afternoon. A Telegram bot token, a Python script that wraps Claude Code’s CLI, some routing logic to direct messages to the right tmux session. That’s it.

Email integration: the inbox as an agent interface

This is the newest channel and honestly it’s been more useful than expected.

Claude Code with Gmail and Google Workspace access turns an inbox into a two-way agent interface. The agent emails things that need attention - summaries, decisions needing sign-off, status updates, draft content. Replies become instructions (“approved, deploy it”, “change the headline”). Forwarded emails and attachments go straight to the agent for processing. A client sends a brief, it gets forwarded, Claude Code reads it, extracts what matters, updates the client context, drafts a response.

Email works differently from Telegram because it’s asynchronous and document-native. Attachments arrive naturally, threads provide context, and the inbox becomes a task queue. The attachment handling has been particularly useful - someone sends a PDF brief or a spreadsheet, forward it, the agent extracts what matters and integrates it into the client context. No downloading, no reformatting, no copy-pasting between apps.

It also creates a natural audit trail. Every instruction, every approval, every piece of context lives in the thread. Three weeks later the decision trail is right there in Gmail.

What’s the best Claude Code setup for managing multiple clients?

Isolated workspaces. Every client gets its own directory with its own CLAUDE.md, status files, and context. No shared state, no shared sessions.

clients/
  client-a/
    CLAUDE.md
    TODO.md
    status/
    src/
  client-b/
    CLAUDE.md
    TODO.md
    status/
    src/

Each client’s CLAUDE.md has everything Claude Code needs to work without any external context - tech stack, deployment config, brand guidelines, current priorities, recent decisions, active blockers. When a tmux session starts for a client, Claude Code reads it and has full context immediately.

Status files get updated as work progresses and bring new sessions up to speed when they start. The memory system, basically. Markdown files that get read at session start.

One thing that’s been interesting: Claude Code starting fresh every session is actually useful. It never carries stale assumptions forward. Every session starts clean, reads current state from files, works from ground truth. The trade-off is that those files need to be accurate and current, otherwise the fresh session just starts from wrong information. Keeping status files updated at the end of every work session is the discipline that makes this work.

Specialist agents are just markdown files

The agent operator concept makes more sense when you see that “managing AI agents” doesn’t need software. It needs clear instructions.

The current agent roster includes an SEO agent that knows audit methodology and how to verify fixes in built output, a blog writer that writes in a specific voice with specific constraints, a voice agent that enforces tone consistency with explicit rules about what not to write, and an ops procedures agent for client updates and status summaries.

Each one is a markdown file. Creating a new one takes maybe 20 minutes of writing clear instructions. No code, no deployment. Need something that handles client onboarding? Write the instructions. Need one that audits accessibility? Write the instructions. Markdown file goes in the agents folder and the system can do something it couldn’t do yesterday.

Opus is what makes this work. Smaller models can’t hold the full CLAUDE.md context and still make good decisions. The instructions end up being long and detailed, and the model needs to internalise all of that while still performing the actual task. Sonnet struggles with the longer instruction sets.

Do you need a framework for Claude Code agents?

We don’t think so. Every agent framework we’ve looked at - LangChain, CrewAI, OpenClaw - adds layers between the operator and the model. Routing, state management, inter-agent communication, monitoring dashboards.

Claude Code with CLAUDE.md files, tmux for persistence, and a Telegram bot for remote access is the entire infrastructure. No dependencies beyond Anthropic. The Telegram bot took an afternoon to build. The CLAUDE.md files are ongoing iteration.

That iteration on the CLAUDE.md files is where most of the actual work lives now. Refining instructions, adding constraints, removing ambiguity, making the agent better at its job through clearer written guidance. In practice, refining agent instructions has been more impactful than tool selection - writing better instructions for tools that are already working.

Whether frameworks become necessary later as the system scales, genuinely unclear. For now, the lightweight approach hasn’t hit a wall.

The complete system

All together:

CLAUDE.md files define every agent, every client, every constraint. tmux keeps sessions alive and isolated. Sub-agents handle parallelisation automatically via Claude Code’s Agent tool. Telegram provides remote control from a phone. Email adds a second channel for longer context and attachments. Client folders keep everything isolated. Specialist agent files turn Claude Code into domain experts on demand.

None of it is particularly complicated, which might be the point. It’s still changing - the email channel is new, the agent roster keeps growing, and the CLAUDE.md files get tighter every week. But the basic architecture has been stable enough to run real client work on, and it hasn’t needed a framework yet.

For the broader architecture, the Claude Code guide and the agent operating system post go deeper.

To get something like this built for a specific business, or to talk through how Claude Code fits into a particular operation, get in touch. Strategic assessments start at $5,000 AUD.