However, developing significant features presents different challenges.

A complete feature involves more than code. It requires product rules, architectural decisions, edge case handling, tests, security checks, review standards, and delivery constraints. As features grow, a single AI session must manage increasing complexity.

This is where the workflow begins to strain.

For example, you might ask your AI assistant to add invoice reminders to a SaaS billing application. Initially, it performs well: inspecting the invoice model, identifying the email service, recognizing the background worker, proposing a plan, and implementing changes. You approve permissions and edits, it runs tests, resolves errors, and updates the summary.

As the session progresses, complexity increases.

The AI must now track the original business rule, tenant boundaries, retry behavior, modified files, added tests, corrected constraints, and instructions on what not to change. While progress remains faster than before, the workflow becomes less organized.

You review the plan again, approve additional edits, identify missing constraints, reiterate rules, request file checks, rerun tests, and examine the diff. You begin to question whether the implementation still aligns with the original intent.

The AI is not failing due to lack of capability; it struggles because the workflow lacks sufficient structure.

A single extended conversation attempts to serve as product analyst, architect, backend engineer, frontend engineer, test engineer, reviewer, and release assistant simultaneously. While this may suffice for small tasks, it becomes unreliable when features involve complex business rules and production risks. Many developers overlook this transition.

Advancing AI-assisted development requires more than improved prompts; it involves designing a more effective system around the model.

If this scenario resonates with you, it does not reflect a lack of skill with AI. Instead, it indicates that your workflow may not be well-suited to the tool.

I am Qudrat Ullah, a tech lead based in London. I collaborate with engineering teams delivering production software and have observed how AI coding tools are transforming daily workflows. In this handbook, I will share practical insights to help you evolve your approach. By the end, you will move beyond repetitive setups and begin building your own software factory. Effective solutions start small and develop over time; avoid aiming for a comprehensive solution in a single day. Start small and continue to grow.

This handbook outlines the workflow I wish I had received when I started using AI for production code. By the end, you will be able to establish your own small software factory, a structured approach to using AI for planning, building, testing, and reviewing features while maintaining control of your codebase.

What You'll learn

• How AI-assisted development actually evolved, and what the shape of that history tells you about where it is going.

• Why "just ask the AI" stops working as soon as a project gets real, and what to do instead.

• The five layers of an AI-assisted workflow: context, knowledge, agents, workflows, and delivery.

• How to use Claude Code's building blocks (CLAUDE.md, skills, subagents, hooks) and let Claude itself generate most of them for you. (You can use any tool. The concepts are the same. I picked one tool for simplicity.)

• How to build a working set of seven specialized agents and an orchestrator that chains them together.

• A hands-on setup you can copy into any Next.js or Node.js project this weekend. If you understand the concepts, you can apply them to any project.

• What I deliberately left out, and where to learn it next.

Who this is For

This guide is accessible to developers new to Claude Code or any AI tool, yet comprehensive enough for senior engineers or tech leads to benefit from the workflow patterns, orchestrator design, review checklist, and delivery section.

Examples reference Next.js, Node.js, and a SaaS billing application, but the concepts are tool-agnostic. Whether you use Cursor, Claude, Aider, Windsurf, Kilo, Cline, or future tools, the same principles apply.

What You'll Be Able to Build by the End

• A CLAUDE.md that captures your project's facts and standards.

• Seven custom subagents that do focused work in their own context: researcher, story writer, spec writer, backend builder, frontend builder, test verifier, and validator.

• One orchestrator (first as a skill, then optionally as an agent) that delegates work across those seven sub agents.

• One reusable skill that encodes a workflow your team runs repeatedly.

• One pre-commit hook for safety.

• A short PR review checklist to ensure AI-generated pull requests are reviewed against the same standards every time.

This is what a "software factory" means in practice. A factory can be scaled to your needs. It is not a large autonomous system, but rather a small set of files in your repository that enables one developer and one AI to function as a coordinated team.

Table of Contents

Part 1: Foundations Before the Factory

• 1. How AI-Assisted Development Evolved

• 2. Why Vibe Coding Breaks Down

• 3. The Five Layers of an AI-Assisted Workflow

• 4. The Context Layer: Explore Before You Build

• 5. The Knowledge Layer: CLAUDE.md, Skills, and Hooks

Part 2: Build the Agent Factory

• 6. The Agent Layer: Seven Agents That Do Focused Work

• 7. The Workflow Layer: The Orchestrator That Runs the Chain

• 8. The Delivery Layer: PRs, Reviews, and the New SDLC

• 9. Build Your First Claude-Powered Software Factory

Part 3: Wrap Up

• 10. What I Did Not Cover (and Where to Go Next)

• 11. Closing Thoughts

Part 1: Foundations Before the Factory

Before building a factory, it is important to understand the current landscape, why existing workflows break down, and the foundational elements required. The first five sections establish this groundwork; construction begins in Section 6.

1. How AI-Assisted Development Evolved

Before building anything, it is helpful to understand the progression of AI in coding. This evolution occurred in few stages, with each stage addressing a specific problem and enabling the next.

Figure 1: Five stages of AI in coding, leading to today's software factory shift.

Manual Coding

In the early workflow, you wrote everything by hand. The editor highlighted the text but did not understand it. You looked things up in books, in docs, on Stack Overflow, then slowly shaped the application line by line. This produced strong developers because every detail had to pass through their heads, but it placed a hard cap on what one person could ship in a week.

Smart editors

Then the editors got useful. IntelliSense, language servers, ESLint, snippet engines, refactoring tools. None of these wrote code for you, but they removed friction inside the file you were already editing. This was the first stage at which developers began to expect the editor to help. It changed the baseline.

Smart Autocomplete

Tabnine and early versions of GitHub Copilot looked at nearby code and predicted what would come next. If you started writing a function calculateInvoiceTotal(items), the tool guessed you wanted to loop over items, multiply quantity by price, and return a total. The editor was no longer completing syntax. It was completing intent. But you still owned the design.

Chat AI

Then chat-based AI arrived, and the workflow split in half. You opened ChatGPT or Claude in another tab and asked for a login page or a registration API. Useful for boilerplate. Bad for anything that depended on your real folder structure, your auth flow, your database schema, or your team's decisions. The generated code looked correct in isolation, but broke when you pasted it in. It helped you draft something initially without typing.

AI in the IDE

Cursor, Claude Code, Copilot Chat, Windsurf, Aider. These closed that gap. The AI could now inspect files, suggest edits across the project, run commands, and help with multi-file work. Instead of "write me a React component," you could ask, "Look at our existing dashboard widgets and add a new metric card in the same style." Much more powerful, because the AI is no longer working from a blank page. This is also the start of vibe coding. You vibe with the AI, it makes changes, you keep going. A lot of people are doing that today and getting real leverage from it.

That power is changing how software is built, but the industry is already moving in another direction. Let's look at what breaks in the vibe coding model.

2. Why Vibe Coding Breaks Down

Vibe coding is the workflow most developers fall into in the first week they use an AI IDE. You ask for a feature. The AI writes code. Something breaks. You paste the error. The AI patches it. Something else breaks. You ask again. Round and round.

On day one, this feels fast. You can build a landing page in fifteen minutes. You can sketch a prototype in an afternoon. Real progress.

On day thirty, the loop turns painful. The same logic appears in three places. The AI has forgotten the convention you set up two weeks ago. New features step on old ones. Tests are missing or shallow. The app works today, then breaks tomorrow because one prompt removed a guard you forgot existed. You are now spending more time supervising the AI than you used to spend writing code yourself.

There are techniques that make this better. Writing better prompts. Maintaining good docs. Keeping the context tight. I covered some of those in my previous article on unblocking the AI PR review bottleneck. Those techniques help, but a single session still drifts when too many jobs land in the same conversation, and that's the challenge we are going to solve.

The Deeper Problem: One Chat, Too Many Jobs

If you watch a real engineering team for a day, you notice that different people have different responsibilities. A product person clarifies the user problem. A senior engineer thinks about architecture. A backend developer designs the API. A frontend developer builds the interface. A test engineer thinks about edge cases. A reviewer decides whether the work fits the codebase.

When you point one AI session at "build the feature," you collapse all of those roles into one conversation. The AI plans, designs, codes, tests, and reviews its own work in the same messy context. That is risky because mistakes compound. A wrong assumption in the plan becomes a wrong database model. A wrong database model becomes a wrong API. A wrong API becomes a wrong UI. By the time you notice, the mistake has spread through the whole feature.

You may start thinking the next stage of AI-assisted development is better prompts. No, it is not, It is a better system.

Use AI to automate structured work, not chaotic work. If your team has no standards, AI will generate inconsistent code faster. If your tests are weak, AI will produce fragile features faster. If your review process is vague, AI will let important risks through faster.

That single idea drives everything that follows.

3. The Five Layers of an AI-Assisted Workflow

Before we get into specifics, here is the mental model this article uses. A working AI-assisted workflow has five layers that stack. Each one only works as well as the one below it.

Figure 2: The five layers. Each one feeds the next; the whole stack is your software factory.

At the bottom is the Context Layer, which is what the AI can see in the current message. Above that sits the Knowledge Layer, which is the persistent project memory the AI inherits at the start of every session. Memory management itself is a huge topic we will cover in a future article (centralized memory, shared knowledge stores, and so on). For now, rely on Claude's session memory. The Agent Layer turns that knowledge into focused workers with their own tools and their own context windows. The Workflow Layer puts an orchestrator on top of those agents and chains them into a real pipeline with validation gates and human approval points. The Delivery Layer is how everything that comes out of the pipeline reaches production safely: pull requests, a review checklist, and CI gates.

If you invest in only one layer, the others remain weak. A team with great agents but no shared CLAUDE.md ends up with inconsistent code. A team with great context discipline but no validation gates ships fragile features fast. The whole point of the model is that you build all five, even if you start small in each one. Also, one more important tip across the teams use same AI and tools for better and consistent results.

Before you build the factory, understand the foundations first.

This article is split into two halves on purpose.

Part 1 (Sections 4 and 5) covers the foundations. Context management. CLAUDE.md. Skills. Hooks. These are not the factory. These are the things you have to understand before the factory can stand on top of them. If you skip them and jump straight to building agents, the factory looks impressive for a week and then falls over. The agents will inherit a messy context. The orchestrator will route work that lacks clear rules. The validator will have nothing to validate against.

Part 2 (Sections 6, 7, 8, and 9) is where you actually build the factory. Seven specialized agents. An orchestrator that runs the chain. A delivery layer that gets the output to production. A hands-on section that wires it all together in your own repo.

A note on Part 1. You might read Sections 4 and 5 and think, "This is still me typing prompts. This is still vibe coding with extra steps." That is fair on the surface, and I want to address it directly. The habits in Part 1 are not the factory. They are the discipline that makes the factory possible. The exploration workflow you do by hand in Section 4 is the same workflow your codebase-researcher agent will automate in Section 6. The CLAUDE.md you write in Section 5 is what every agent will read at the start of every task. Part 1 teaches you the moves. Part 2 teaches the machine to make them for you.

If you already practice good context hygiene and have a CLAUDE.md you trust, skim Part 1 and head straight to Section 6. If you do not, take the time. The factory is only as good as what it stands on.

4. The Context Layer: Explore Before You Build

Context is the AI's working memory. It is your prompt, the files you opened, the previous messages, your project rules, the documentation you injected, the terminal output, and the errors. Anything else the model can see while it is helping you.

Senior engineers carry a lot of project knowledge in their heads. They know why a decision was made, where the risky files live, which patterns the team follows, and what should not be touched. AI does not automatically know any of that. It only knows what is in its context.

Even with very large context windows, more is not better. Too much uncontrolled context makes the model worse. It mixes old decisions with new ones. It follows an outdated file pattern. It carries forward a wrong assumption that you corrected three messages ago. The goal is not to give the AI everything. The goal is to give it the right information at the right time which save computing time and cost both.

Habit 1: Explore before you build

The single biggest mistake developers make with AI in the IDE is asking for code as the first move. The AI accepts the prompt, makes guesses to fill the gaps in your description, and starts generating. That is when bad designs sneak in. Strongly recommend avoid that.

A better move is to treat the first phase as exploration, not implementation. You are not asking the AI to build anything yet. You are asking it to read the existing code and tell you what is there. During this process you will observe AI will discover things which it finalize wrong initially.

Concrete example. Imagine you run a SaaS billing platform built with Next.js (App Router) on the frontend and Node.js services on the backend. The app has customers, subscriptions, invoices, a webhook handler that updates payment status, and a Resend integration for transactional email. You want to add reminder emails for unpaid invoices.

If you tell Claude Code, "add invoice reminders," you are gambling. It might do something reasonable. It might also create a new scheduler when you already have one, send reminders to customers who already paid, ignore timezone handling, hardcode business rules into the API route, or skip audit logs entirely. None of that is the AI being bad. It is the AI guessing because you asked it to.

Here is the controlled version, step by step.

Step 1. Open Claude Code in plan mode and start with a read-only prompt. The goal is to make the AI describe the relevant parts of your codebase before any code is written.

I want to add reminder emails for invoices that have been unpaid
for more than 7 days. Before suggesting anything, please:

1. Read the invoice, payment, and email-sending code in this repo.
2. Tell me how invoices are created and where their status is stored.
3. Tell me how transactional emails are sent today.
4. Tell me whether we already have a background job system or scheduler.
5. List the files that would most likely change if we added reminders.

Do not write any code yet. I want a clear map first.

The prompt above can be written in many ways. Also can references docs folder if CLAUDE.md does not have clear mapping or you want to give more context to the AI for better results. The purpose is to show the shape: ask for understanding before action.

Step 2. Read the response carefully. This is the moment to spot wrong assumptions while they are cheap to fix. If the AI says "I will use cron," but you actually have BullMQ workers running, correct that now. Because during codebase discovery it's possible it has not discovered BullMQ code and that information is in your head.

Step 3. Once the map is right, ask for options, not code. You want a small comparison, not a solution.

Based on what you just found, suggest 3 ways we could implement
invoice reminders.

For each option, explain:

- how it would work end-to-end
- which existing parts of the system it reuses
- which new files or DB changes it needs
- the main risks (timezone, multi-tenant, retries, deduplication)
- Which option would you recommend and why

Do not edit any files yet.

Step 4. Pick one option, then ask Claude Code to write a one-page brief: goal, approach, business rules, data model changes, tests needed, edge cases, open risks. Read the brief in under a minute. If something is missing, ask for a revision before moving on.

Step 5. Open a fresh Claude Code session and paste only the brief into it. This is the move most people skip. During exploration, the AI discussed multiple options. Some were rejected. Some were partially correct. You do not want all that noise carried forward when implementation starts. A clean session means a clean context.

Step 6. Ask about the new session's implementation plan and read it slowly. Look for things like "we will store processed invoice IDs in memory." That is a red flag. Memory is lost on restart and is not shared across multiple servers, so the same reminder could be sent twice. Catching that in the plan costs five minutes. Catching it after Claude has changed ten files costs an afternoon.

Step 7. Build, then ask Claude to explain back. After the implementation, do not blindly commit. Ask the AI to walk you through the important decisions, list the tests it added, and update the docs with anything operators need to know. Trust but verify.

The shape of this workflow is:

inspect → compare options → pick approach → write brief → start clean → plan → review → build → explain back

Compare that to the vibe-coding shape: prompt → generate → run → paste error → repeat. The first one is controlled progress. The second is accidental progress, which does not scale.

This whole workflow is what you do today, by hand. In Section 7, you will see how an orchestrator can run most of it for you while you only step in at the review points.

Habit 2: Watch for Context Drift

Even with a clean start, bad information can sneak into a long session. Once a wrong assumption enters the context, the model keeps building on top of it. I call this context drift, and it is the most common reason a working session quietly produces a broken codebase. One small wrong assumption can spread across many files before you notice.

Figure 3: How a vague prompt drifts into spreading damage, and the only reliable way out.

A real example. You give Claude this prompt:

Add subscription management to our SaaS. Users should be able to create a subscription and cancel it later.

That prompt is too broad. The AI guesses ownership and creates something like:

User
└── Subscription
      ├── planName
      ├── status
      └── renewalDate

Looks fine on the surface. Then you remember your real business rule: a company account has many users, and the subscription belongs to the company, not the individual user. That difference is huge, and the AI has already designed around the wrong owner.

If you only say "no, subscriptions belong to companies," Claude tries to patch. You end up with both user.subscriptionId and company.subscriptionId floating around, defensive comments where they should not exist, and renamed code that still behaves like the old design.

Rule of thumb: If the AI makes a small typo, correct it inline. If it makes a wrong architectural assumption, throw the conversation away and start a new session with a stronger prompt. Small mistakes can be patched. Deep design mistakes should not be patched inside a polluted conversation.

The cleaner move is to discard the chat, edit your original prompt, and start over with the rule baked in:

We need subscription management for our SaaS.

Important business rules:
- Subscriptions belong to a company account, not an individual user.
- A company can have many users.
- Only company admins can change the subscription.
- Billing history is visible to admins only.
- Cancelled subscriptions remain active until the end of the billing period.

Before writing code, inspect our existing account, user, and billing models.
Then suggest an implementation plan. Do not edit files yet.

Now the AI starts from the correct mental model. The first version is a guess. The second version is a design.

Habit 3: Pin the AI to your installed versions

Models know a lot, but they do not always know the exact version of your framework, your library, or your team standard. Sometimes they answer from older training data. Sometimes they give you a generic answer that worked in a tutorial three years ago and does not fit your project today.

A better prompt forces the AI to ground itself in your real installed versions:

Before writing code, inspect this project's structure and package.json.

This project uses Next.js App Router. Use the authentication library
version that is actually installed. Look up the current docs for that
specific version. Then explain the recommended file structure before
editing anything.

Same idea for Tailwind versions, Stripe SDK versions, Prisma migrations, React 18 vs 19 differences. Anywhere there is a real version-to-pattern dependency, make the AI ground itself in your installed versions and the current docs, not its training memory. Without it, the model produces average internet code and keep fixing errors and after a while will reach to correct information. With it, the model produces code that fits your project.

A useful tool here is Context7. It is a plugin that fetches the current docs for the exact installed version of each library. You can install it in Claude Code and reference it in your prompts or knowledge files so the model always pulls current docs before writing code. I use it regularly.

5. The Knowledge Layer: CLAUDE.md, Skills, and Hooks

The Context Layer covers a single conversation. The Knowledge Layer covers everything that survives between conversations. This is where most teams' AI workflows quietly fail. They keep re-explaining the same project facts to the AI, every day, in every chat. Capturing that knowledge once, in the right place, is what turns a good AI workflow into a repeatable one.

Claude Code gives you four building blocks for this layer. Picking the right block for the right kind of knowledge is half the skill.

Figure 4: Four building blocks. Each one feeds your Claude Code session in a different way.

CLAUDE.md: The Lasting Facts

CLAUDE.md is a Markdown file at the root of your repo (or at ~/.claude/CLAUDE.md for personal-level instructions). It is loaded automatically every time you open a Claude Code session in that project, and it is where lasting facts live. If you have multiple projects in a monorepo you can have one for each project.

A working CLAUDE.md for a Next.js + Node.js SaaS billing app looks like this:

# Project Instructions

This is a SaaS billing application.

## Stack

- Next.js 14 (App Router) with TypeScript
- Node.js services for billing and email
- Prisma + PostgreSQL
- Auth.js for authentication
- Resend for transactional email
- BullMQ for background jobs

## Commands

- npm run dev - start the dev server
- npm test - run unit tests
- npm run typecheck - type-check the project
- npm run lint - lint the project
- npx prisma migrate dev - run migrations locally

## Architecture

- Business logic lives in services or domain modules.
- API routes stay thin and call into services.
- Use the existing email template system; do not add a new one.
- The BullMQ worker handles all scheduled jobs. Do not add cron.
- Tenant isolation is enforced at the service layer, not the route.

## Documentation

For deeper context, consult these before guessing:

- `docs/architecture.md` — service boundaries, request flow, tenant isolation model
- `docs/billing.md` — Stripe webhook handling, invoice lifecycle, proration rules
- `docs/email.md` — template system, Resend setup, list of available templates
- `docs/jobs.md` — BullMQ queue names, job patterns, retry/backoff policy
- `docs/db.md` — schema conventions, tenant isolation patterns, soft-delete rules
- `docs/runbooks/` — production incident runbooks
- `prisma/schema.prisma` — source of truth for the data model
- ADRs in `docs/adr/` — past architecture decisions; read before contradicting one

For Next.js, Prisma, Auth.js, BullMQ, or Resend specifics, check the official docs rather than guessing.

## Testing

- Every feature has success, validation failure, and not-found tests.
- Use test data builders, not inline setup objects.
- Do not mock the database unless existing tests do.

## Don't do

- Do not log raw payment payloads.
- Do not return database errors directly to the client.
- Do not edit migrations after they have been merged.

Keep CLAUDE.md tight. 100 to 300 lines is healthy. If a section grows into a multi-step procedure, that procedure belongs in a skill, not in CLAUDE.md. CLAUDE.md is for facts and rules. Workflows go in the next building block.

A trick for growing your CLAUDE.md naturally. Every time the AI makes a mistake that surprises you, ask yourself if a rule in CLAUDE.md would have prevented it. Add the rule. Over a few weeks, your CLAUDE.md becomes a record of every assumption the AI got wrong, and your future sessions get noticeably better.

Skills: The Workflows You Keep Retyping

A skill is a small folder with a SKILL.md file inside. Claude scans every skill's name and description on startup, but only loads the body when the skill is needed. That progressive loading is what makes it cheap to keep dozens of skills around without slowing the model down.

Use a skill when you keep pasting the same instructions into chat: a commit format, a deployment checklist, a build process, a PR review pattern. Use CLAUDE.md for facts. Use skills for procedures.

The neat trick is that you do not have to write a skill by hand. Claude will write it for you. Open Claude Code in the project, then ask:

I want to create a Claude Code skill that captures how I build a production feature on this project. The skill should cover:

1. How to read CLAUDE.md and the technical brief before writing code.

2. How to look at 2-3 existing similar features and match their
   patterns.

3. How to write unit tests alongside the production code as normal good engineering (not as a strict TDD red-green loop).

4. How to run typecheck, lint, and the test suite at the end.

5. The conventions our codebase already follows: naming, error handling, where business logic lives, how tests are structured.

Create the skill at .claude/skills/build-with-tests/SKILL.md.
Use the recommended Claude Code skill format with proper YAML
frontmatter (name, description). Make the description specific
enough that the skill triggers automatically when I ask to
build, implement, or extend a feature.

Show me the file before writing it.

Claude reads your existing code, infers the patterns, and proposes a skill file. You review it, edit anything that does not match your taste, then save. The skill is now part of the repo, and every future session can use it. You can also use Claude's skill-creator to bootstrap new skills with /skill-creator create me a new skill....

Here is the kind of file Claude will produce:

---
name: build-with-tests
description: Use this skill when implementing a feature or extending existing behaviour. Reads CLAUDE.md and the technical brief first, matches existing patterns, writes production code with unit tests alongside it, and runs the project's typecheck and test commands at the end. Triggers on: "build", "implement", "add", "extend", "ship the feature".
---

Process:

1. Read CLAUDE.md so you know the project rules and stack.
2. Read the technical brief so you stay inside its scope.
3. Look at 2-3 similar features in the codebase. Note their file layout, naming, error handling, and test structure.
4. Implement the feature in the smallest coherent steps you can.
For each step:
   - Write the production code.
   - Write a unit test that covers the new behaviour.
   - Run the test and confirm it passes.
5. When the feature is complete, run the full typecheck, lint,
   and test commands from CLAUDE.md.
6. Return a short summary: files changed, patterns reused, any
   rule you would suggest adding to CLAUDE.md.

Conventions used in this project:

- File names follow the existing folder structure.
- Tests live next to the code they cover (or in tests/ if that
  is the existing pattern).
- Use builders from test/builders/ for any entity setup.
- Cover success, validation failure, and one edge case per
  behaviour.

Rules:

- Do not refactor unrelated code.
- Do not change files outside the agreed scope.
- Do not add new dependencies without explicit instruction.
- If you cannot make the tests pass without violating a rule,
  stop and report the conflict.

With this skill saved, you no longer paste the process every time. You can just write:

Use the build-with-tests skill to implement the invoice reminder service.

The most common skill mistake. Avoid the mega-skill. A single SKILL.md trying to handle commits, PRs, branch naming, and changelog updates all at once tends to fire less reliably and confuse the model when two parts conflict. Split them. A good skill fits on one screen.

Hooks: Automatic Gates and Workflow Triggers

Some parts of an AI workflow should not depend on the model remembering them.

A prompt can say, "run the tests before finishing." CLAUDE.md can say, "do not edit secret files." A skill can say, "validate the implementation before opening a PR." But those are still instructions. The model can forget. The model can choose to skip.

A hook is different.

A hook is an automatic action that runs at a specific point in the Claude Code session lifecycle. It can run a shell command, call an HTTP endpoint, or trigger a prompt or agent-based check depending on how you configure it.

That makes hooks useful for two things:

1. Gates. Stop or warn when something unsafe happens.

2. Workflow triggers. Notify another system when something important happens.

In a software factory, agents do the work, but hooks enforce the rules around them.

Claude Code hooks can run at lifecycle events such as:

• UserPromptSubmit: before Claude processes your prompt

• PreToolUse: before Claude runs a tool

• PostToolUse: after a tool succeeds

• Stop: when Claude finishes a response

• SubagentStart: when a subagent starts

• SubagentStop: when a subagent finishes

A simple, useful hook is a pre-commit gate that blocks credential files from ever being committed. Save this as .claude/hooks/pre-commit.sh:

#!/usr/bin/env bash
# Block commits that would include sensitive files.

if git diff --cached --name-only \
   | grep -qE '\.(env|key|pem)$|secrets\.json|creds\.md'; then
  echo "BLOCKED: attempt to commit sensitive files"
  exit 1
fi

Wire it into your Claude Code hook configuration so it runs before commits. The configuration syntax lives in the official Claude Code hooks docs, but the shape is JSON and looks roughly like this:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/pre-commit.sh"
          }
        ]
      }
    ]
  }
}

That is deliberately minimal. In a real project you would also use PostToolUse to run formatters after edits, and Stop to run typecheck and tests before Claude finishes a response. Once it is wired, the hook runs every time, regardless of what the model thinks.

A few other hooks that pay off quickly:

• PostToolUse on Edit: run the formatter so every AI edit comes out formatted.

• Stop: run typecheck and tests, refuse to stop if either fails.

• SubagentStop on validator: post the validator's findings to your team Slack channel automatically.

Hooks matter because they cannot be argued with. The model can suggest, plan, and write. The lint, the type-check, and the test run on every change. That asymmetry is what keeps a software factory honest.

How the Four Blocks fit Together

A simple way to remember which block to reach for:

• CLAUDE.md answers "what is true here?" Project facts and rules.

• Skills answer "how is this done?" Repeatable procedures.

• Subagents answer "who should do this?" Focused workers (next section).

• Hooks answer "what is enforced?" Deterministic gates.

You will use all four. CLAUDE.md tells the AI the rules of your codebase. Skills give the AI repeatable playbooks. Subagents give it focused workers. Hooks make sure the rules are real and not optional.

The four blocks are the foundation. Section 6 is where we build the workers that actually do the factory's work.

Part 2: Build the Agent Factory

You now have everything Part 1 promised. You know how to keep the AI's context clean. You have a CLAUDE.md it can lean on. You understand skills and hooks. That is the ground floor.

The next four sections are the factory itself.

Section 6 builds the seven specialized agents. Section 7 puts an orchestrator on top of them so the chain runs itself. Section 8 covers how the factory's output reaches production safely. Section 9 is the hands-on walkthrough where you build the whole thing in your own repo.

By the end of Part 2, the workflow you have been doing by hand will be running on its own. You will type one prompt. The orchestrator will route the work. The agents will do their focused jobs. You will step in at three approval points where your judgement matters. That is the shift.

6. The Agent Layer: Seven Agents That Do Focused Work

Now we get to the part that makes a factory a factory.

So far we have been giving the AI better instructions and better memory. But the AI is still one worker doing every job in the same chat. That is fine for small tasks. It does not scale to real feature work.

The fix is to split the work across specialized agents. In Claude Code these are called subagents. A subagent is not just a longer chat message. It is a focused worker with its own job description, its own tool permissions, and its own context window. That last piece is the one that matters most.

When the main session delegates work to a subagent, the subagent does the heavy reading or processing in its own context. It returns only a short summary to the main thread. The verbose part (file searches, log dumps, multi-step exploration) never bloats your main conversation.

Picture it like this. Your main Claude Code session is the lead engineer. Subagents are specialists you call in for specific tasks. A researcher who maps the codebase. A story writer who turns ideas into user stories. A spec writer who turns stories into technical briefs. A backend builder who writes API routes, services, and database access. A frontend builder who writes components and pages. A test verifier who writes acceptance tests against the user story once the feature is built. A validator who compares everything against the brief.

Each one is good at one thing. None of them tries to do everything.

Why One Big AI Session is Not Enough

Imagine you ask your main session "build the invoice reminder feature." The session inspects files, designs the data model, writes API routes, builds UI, adds tests, and updates documentation. That sounds great until you realize one conversation is now carrying product thinking, architecture, database design, backend implementation, frontend implementation, testing, documentation, and self-review. The context is heavy, the model mixes responsibilities, and the same conversation that designed the feature is also reviewing it. That is a self-graded paper.

Splitting work into subagents fixes that. Each subagent has a narrow responsibility, a clean context window, and only sees what it needs. The validator does not see how the code was written. It sees what was supposed to be built and what is now on disk. That is exactly the gap a real reviewer looks for.

Let Claude Write the Agent File for You

You can write a subagent file by hand if you want (it is just Markdown with YAML frontmatter) but there is rarely a reason to. The cleaner workflow is to use the /agents slash command and let Claude itself draft the file from your description.

Here is the workflow, end to end. Open Claude Code in your project and type:

/agents

That opens the agent management view. Choose to create a new project-level agent (which lives at .claude/agents/<name>.md and gets committed to your repo so the whole team uses it) and ask Claude to generate it for you. Claude will ask what the agent should do, what tools it should have, and what model it should run on.

The key idea is this: you describe the role you want. Claude writes the file. You review, edit, save, commit. Repeat for every agent your team needs.

Tool Access and Model Selection are Part of the Design

Before we look at the seven agents, two design choices apply to every one of them.

Tool access. A common beginner mistake is giving every agent every tool. That is risky. If an agent's job is to inspect architecture, it should not have Edit. If its job is to review code, it should not have Write. Restricting tools is how you make a subagent's behaviour match its description. The researcher cannot accidentally write code. The validator cannot accidentally fix what it found. The backend builder cannot accidentally edit frontend files. That separation is the point.

Model selection. Inspection and review do not need a top-tier model. Routing them to a smaller, faster, cheaper model (Haiku) is one of the practical reasons subagents exist. Save the top-tier model (Sonnet, or Opus when reasoning quality really matters) for the work that needs it: the spec writer, the builders, the test verifier, and the validator.

The Anatomy of a Good Agent Definition

Before we look at the seven specific agents, here is the shape every good agent definition follows. You can use this as a template to design your own agents later. Anything the agents below have, you can copy. Anything they do not have but your team needs, you can add.

Two things beginners almost always miss when they design their first agent. The first is boundaries. They tell the agent what to do but not what it must not do, and the agent ends up doing both. The second is output format. They tell the agent what to think about but not how to return the result, so each invocation produces a slightly different shape and the next agent in the chain cannot rely on it. Both of those are in the template below.

Here is the template, written as if you were briefing a new agent on day one:

Subagent name:
  <short-kebab-case-name>

Purpose:
  One sentence on why this agent exists and what it is for.

Main responsibility:
  One sentence on the single job this agent owns.

What it should investigate / do:
  - Specific thing one
  - Specific thing two
  - Specific thing three
  (Be concrete. "Find similar features already implemented" is
   better than "understand the codebase".)

What it should NOT do:
  - The action it must never take (for example, edit files)
  - The decision it must never make (for example, invent rules)
  - The tool it must never use
  - The scope it must never widen
  (Boundaries are what make an agent's behaviour predictable.)

Tool access:
  Only the tools this agent actually needs.

Model:
  haiku for cheap inspection, sonnet for reasoning,
  opus when reasoning quality is critical.

Output format:
  1. Section one of the result (for example, "Relevant files")
  2. Section two (for example, "Existing patterns to follow")
  3. Section three (for example, "Risks or conflicts")
  (This is the contract with the next agent in the chain.
   A consistent output shape is what makes chaining reliable.)

Behaviour rules:
  - Short, specific rules the agent must follow every time
  - Limits on length, scope, or assumptions
  - When to ask a clarifying question instead of guessing

That is the shape. You hand it to Claude using the /agents slash command and ask Claude to create the agent file from the template. Claude turns it into a complete .claude/agents/<name>.md with the right YAML frontmatter, formatted system prompt, and tool restrictions.

The seven agents below all follow this shape. Once you understand the template, you can design your own. A design-system reviewer that checks new components against your tokens. An accessibility auditor that reads new UI code and flags issues. A migration writer that turns a schema change into a Prisma migration with the right naming. A release-note drafter that reads recent merges and writes a summary. Anything your team keeps doing by hand and would like to capture once.

The Seven Agents at a Glance

Before drilling into each one, here is the whole chain on one screen.

These seven cover the path from feature idea to a vertical slice ready for PR. They are not the canonical set. They are an opinionated starting point. Section 6 ends with how to grow the library beyond these.

Now let's build the seven.

Agent 1: Codebase-Researcher

This is the explore-before-build habit from Section 4, captured as a reusable worker. It maps the relevant parts of the codebase and returns findings. It never writes code.

Type /agents and use this description:

Create a project-level subagent named codebase-researcher.

Its job: inspect this codebase and explain how a specific area
works, without editing anything.

Inputs: a question about an area of the codebase (for example, "how does invoice creation work today?").

Outputs:
- a short list of the relevant files with paths
- a concise summary of the current architecture in that area
- the patterns and conventions in use
- risks or missing information the next agent should know about

Tool access: Read, Grep, Glob only. No Write. No Edit. No Bash.

Recommended model: haiku (this is cheap inspection work).
Recommended color: teal.

Behaviour rules:
- Never edit files.
- Never run commands that modify state.
- Keep the summary under 400 words.
- If a question is ambiguous, ask one clarifying question first.

Claude reads your description, picks reasonable defaults, and writes the file for you. In your terminal you will see something like:

I have created the agent at .claude/agents/codebase-researcher.md with the following content. The agent is restricted to read-only tools (Read, Grep, Glob) so it cannot accidentally modify your codebase. I have set the model to Haiku to keep inspection cheap. Restart your Claude Code session to load the new agent, then invoke it with @codebase-researcher followed by the area of code you want explained.

You will get an agent file like this:

---
name: codebase-researcher
description: Read-only investigator that maps the relevant parts of the codebase before any code is written. Returns the files involved, the patterns in use, similar features that already exist, and risks the next agent should know about. Use as the first step of any feature.
tools: Read, Grep, Glob
model: haiku
color: teal
---

You are a read-only investigator for this project. Your only
job is to inspect the codebase and explain how a specific area
works so the next agent has a clear, accurate map to build on.

When invoked, expect a question about an area of the codebase,
for example: "how does invoice creation work today?" or "where
is the email-sending code?".

Produce, every time, in this exact order:

1. **Relevant files**
   File paths grouped by role (services, API routes, models,
   workers, tests). Cite paths exactly.

2. **Existing patterns to follow**
   Naming conventions, folder structure, how business logic is
   organised, how errors are handled, how tests are structured.

3. **Similar feature examples**
   Two or three existing features in the codebase that solve
   a similar shape of problem. Cite paths.

4. **Risks or conflicts**
   Places where the proposed change could break old features,
   tenant boundaries that need to be preserved, timezone
   handling that already exists, anything that smells fragile.

5. **Recommended implementation plan (high level)**
   A short bullet list of how the change should fit into the
   existing system. Do not write code. Do not commit to one
   approach over another if more than one is reasonable.

6. **Tests that should be updated or added**
   Existing test files that probably need updates, plus the
   new test cases you would expect.

7. **Open questions** (only if you have any)
   Things that are genuinely unclear from the codebase. Never
   guess. Ask instead.

Behaviour rules:

- Never edit files.
- Never run commands that modify state.
- Keep the whole summary under 400 words.
- If the user's question is ambiguous, ask one clarifying
  question before investigating.
- Cite every file path exactly.
- If the answer requires running code or seeing live data,
  say so. Do not guess from filenames alone.

You will see this same flow for every agent below. The pattern is always: you describe the role using the /agents slash command, Claude generates the actual file, you review it, and you commit it to the repo. If you prefer to skip the /agents flow entirely, you can paste the generated files directly into .claude/agents/<name>.md and they will work the same way.

Agent 2: Story-Writer

Turns a rough feature idea into a user story with acceptance criteria, edge cases, and out-of-scope items. This is the agent that catches things before any code is written.

Create a project-level subagent named story-writer.

Its job: take a rough feature idea (from the user) plus
exploration findings (from codebase-researcher) and produce
a clear user story.

Inputs:
- a rough feature description
- exploration findings from codebase-researcher
- any product or business rules already known

Outputs:
1. One user story in the form:
   "As a <role>, I want <behaviour>, so that <outcome>."
2.- Acceptance criteria that a test can verify directly. Cover the happy path, the obvious failure paths, and the rules from the brief.
3. A list of edge cases worth thinking about.
4. A list of explicitly out-of-scope items.

Tool access: Read only.
Recommended model: sonnet.
Recommended color: purple.

Behaviour rules:
- Use plain language. Avoid jargon.
- Do not invent product rules. If something is unclear, list
  it as an open question instead of guessing.
- Keep the story under one page.

Claude responds:

I have created the agent at .claude/agents/story-writer.md with the following content. Restart your session to pick it up. You can invoke it with @story-writer and a feature idea, ideally with the codebase researcher's findings attached.

---
name: story-writer
description: Turns a rough feature idea plus codebase exploration findings into a clear user story with acceptance criteria, edge cases, and out-of-scope items. Read-only. Use this after the codebase researcher has produced findings, before any technical brief is written.
tools: Read
model: sonnet
color: purple
---

You are the user story author for this project. Your job is to
turn a rough feature idea into a clear, testable user story
that the rest of the chain can build against.

When invoked, expect to receive:

- A rough feature description from the user.
- Exploration findings from the codebase-researcher agent.
- Optionally, any product or business rules already known.

Produce, every time, in this exact order:

1. **User story**
   One sentence in the form:
   "As a <role>, I want <behaviour>, so that <outcome>."

2. **Acceptance criteria**
   Statements that a test can verify directly. Cover the happy
   path, the obvious failure paths, and the rules from the
   brief.

3. **Edge cases worth thinking about**
   Boundary conditions, retries, multi-tenant concerns,
   permission edges, anything that often goes wrong.

4. **Out of scope**
   Things this story explicitly does not cover, so the team
   knows what NOT to build.

5. **Open questions** (only if you have any)
   Things that are genuinely unclear from the input. Never
   invent answers. Always ask instead.

Behaviour rules:

- Use plain language. Avoid product or framework jargon.
- Never invent business rules. If a rule is missing, ask.
- Keep the whole story to one page or less.
- Do not write code or technical design. That is the spec
  writer's job.

Agent 3: Spec-Writer

Turns the approved user story plus exploration findings into a technical brief. Data model changes, background flow, API changes, frontend changes, tests required, risks. This agent is read-only. It cannot edit code.

Create a project-level subagent named spec-writer.

Its job: take an approved user story and exploration findings,
and produce a technical brief that the backend builder, frontend
builder, and test verifier can follow.

Inputs:
- an approved user story
- exploration findings from codebase-researcher
- CLAUDE.md and any relevant project rules

Outputs (one short Markdown document):
- Data model changes
- Background flow / process flow
- API changes (if any)
- Frontend changes (if any)
- Tests required (success, failure, edge cases)
- Risks and open questions
- Files that will change

Tool access: Read, Grep, Glob.
Recommended model: sonnet.
Recommended color: indigo.

Behaviour rules:
- Read CLAUDE.md before writing the brief.
- Prefer reusing existing infrastructure. Call out any new
  scheduler, new database, or new third-party dependency.
- Highlight tenant isolation and timezone concerns explicitly.
- Never edit files.

Claude responds:

I have created the agent at .claude/agents/spec-writer.md with the following content. The agent is read-only and is configured to read CLAUDE.md before producing each brief, so the brief stays consistent with your project's architecture rules.

---
name: spec-writer
description: Turns an approved user story plus exploration findings into a short technical brief that the build and verification agents can follow. Read-only. Always reads CLAUDE.md before writing. Use after the user story has been approved.
tools: Read, Grep, Glob
model: sonnet
color: indigo
---

You are the technical brief writer for this project. Your job
is to turn an approved user story plus the codebase researcher's findings into a short, actionable brief that downstream agents can follow without ambiguity.

Before writing:

1. Read CLAUDE.md for the project's stack, architecture rules,
   and "don't do" list.
2. Read the user story and the researcher's findings.
3. If something material is missing or unclear, list it as an
   open question. Do not guess.

Output a short Markdown document with these sections, in order:

**Data model changes**

- Which models change. What fields. What types.
- Any migration considerations.

**Background flow / process flow**

- Step-by-step description of how the behaviour runs.
- Which existing infrastructure it reuses.

**API changes**

- New or changed endpoints, with request and response shape.
- Auth and authorization requirements.

**Frontend changes**

- New or changed components, hooks, or pages.
- How they call the API and handle loading / error states.

**Tests required**

- Success cases.
- Failure cases.
- Edge cases (boundaries, retries, deduplication).
- Acceptance tests at the user-story level.

**Risks and open questions**

- Tenant isolation concerns. State them explicitly.
- Timezone concerns. State them explicitly.
- Anything else the team should decide before code is written.

**Files that will change**

- Bullet list of file paths, grouped by backend / frontend / tests.

Behaviour rules:

- Prefer reusing existing infrastructure. Any new scheduler,
  new database, or new third-party dependency must be called
  out explicitly with a justification.
- Tenant isolation and timezone handling must always be
  addressed, even if only to say "no tenant boundary applies"
  or "timezone is irrelevant for this feature."
- Never edit files.
- Keep the whole brief under one page where possible.

Agent 4: Backend-Builder

This is the first of the build-side agents. Its job is the backend half of a feature: API routes, services, database access, background jobs, and the unit tests that cover its own code. It does not touch frontend files.

A note before the prompt. Writing "only edit backend files" inside an agent definition is guidance, not a hard security boundary. The agent will usually obey, but the strongest enforcement comes from Claude Code permissions, hooks that reject edits to specific paths, or CI checks that fail when a PR touches files outside its declared scope. Use prompt rules for direction. Use hooks and CI for enforcement.

Create a project-level subagent named backend-builder.

Its job: implement the backend half of a feature described in
the technical brief. That means API routes, services, database
access, background jobs, and unit tests for the code it writes.

Inputs:
- the approved technical brief
- the codebase researcher's findings
- CLAUDE.md and any relevant project rules
- the build-with-tests skill (project skill)

Outputs:
- backend code that implements the brief
- unit tests that cover the new behaviour
- a short summary: files changed, patterns reused, any rule
  worth adding to CLAUDE.md

Tool access: Read, Edit, Write, Bash. Restricted to backend
folders (services, API routes, workers, migrations, server-side
helpers, and their tests).
Recommended model: sonnet.
Recommended color: green.

Behaviour rules:
- Use the build-with-tests skill for conventions.
- Read CLAUDE.md and the brief before editing anything.
- Only edit backend files. Do not touch React components, pages,
  or client-side hooks.
- Match existing patterns. Reuse existing helpers, services, and templates instead of writing new ones.
- Do not add new dependencies without explicit instruction.
- Run typecheck, lint, and the test suite at the end. Report
  pass/fail and any unexpected failures.
- If a project rule that would have helped is missing from
  CLAUDE.md, surface it as a suggested addition.

Claude responds:

I have created the agent at .claude/agents/backend-builder.md with the following content. This agent has full edit and bash access, scoped to backend folders. I have added explicit rules so it does not stray into frontend files and so it always uses the build-with-tests skill for conventions.

---
name: backend-builder
description: Implements the backend half of a feature: API routes, services, database access, background jobs, and unit tests. Reads CLAUDE.md, the technical brief, and matches existing patterns. Uses the build-with-tests skill. Restricted to backend folders.
tools: Read, Edit, Write, Bash
model: sonnet
color: green
---

You are the backend implementation worker for this project.
Your job is to implement the backend half of the feature
described in the approved technical brief.

Before you edit anything:

1. Read CLAUDE.md so you know the project rules and stack.
2. Read the technical brief so you stay inside its scope.
3. Load the build-with-tests skill for conventions.
4. Look at 2-3 similar backend features in the codebase and
   match their patterns.

Implementation rules:

- Only edit backend files: services, API routes, workers,
  migrations, server-side helpers, and their tests.
- Never edit React components, pages, or client-side hooks.
  That is the frontend-builder's job.
- Match existing patterns. If a helper, service, or template
  already does what you need, use it instead of writing a new
  one.
- Do not refactor unrelated code.
- Do not add new dependencies without explicit instruction.
- Write unit tests alongside the production code.

After you edit:

1. Run the project's typecheck, lint, and test commands (from
   CLAUDE.md).
2. Confirm all tests pass.
3. Return a short summary:
   - Files added / edited (backend only)
   - Patterns and helpers reused
   - Anything you noticed that would benefit from a CLAUDE.md
     rule

If you cannot complete the work without violating one of the
rules above, stop and report the conflict.

Agent 5: Frontend-Builder

This is the second build-side agent. Its job is the frontend half of the same feature: components, pages, hooks, client-side state, and the unit/component tests that cover its own code. It does not touch backend files. It consumes the API contract the backend builder has already produced.

Create a project-level subagent named frontend-builder.

Its job: implement the frontend half of a feature described in
the technical brief. That means React components, pages, hooks,
client-side state, and component tests for the code it writes.

Inputs:
- the approved technical brief
- the codebase researcher's findings
- the backend builder's summary (so it knows the API contract)
- CLAUDE.md and any relevant project rules
- the build-with-tests skill (project skill)

Outputs:
- frontend code that implements the brief
- component and unit tests that cover the new behaviour
- a short summary: files changed, patterns reused, any rule
  worth adding to CLAUDE.md

Tool access: Read, Edit, Write, Bash. Restricted to frontend
folders (components, pages, hooks, client-side helpers, and
their tests).
Recommended model: sonnet.
Recommended color: blue.

Behaviour rules:
- Use the build-with-tests skill for conventions.
- Read CLAUDE.md and the brief before editing anything.
- Only edit frontend files. Do not touch services, API routes,
  workers, or migrations.
- Consume the API exactly as the backend builder produced it.
  Do not invent endpoints or response shapes.
- Match existing component patterns: styling, accessibility,
  loading and error states.
- Do not add new dependencies without explicit instruction.
- Run typecheck, lint, and the test suite at the end. Report
  pass/fail and any unexpected failures.
- If a project rule that would have helped is missing from
  CLAUDE.md, surface it as a suggested addition.

Claude responds:

I have created the agent at .claude/agents/frontend-builder.md with the following content. This agent has full edit and bash access, scoped to frontend folders. It consumes the API contract the backend builder produced, rather than inventing endpoints of its own.

---
name: frontend-builder
description: Implements the frontend half of a feature: components, pages, hooks, client-side state, and component tests. Reads CLAUDE.md, the technical brief, the backend builder's summary, and matches existing component patterns. Uses the build-with-tests skill. Restricted to frontend folders.
tools: Read, Edit, Write, Bash
model: sonnet
color: blue
---

You are the frontend implementation worker for this project.
Your job is to implement the frontend half of the feature
described in the approved technical brief, consuming the API
that the backend builder has already produced.

Before you edit anything:

1. Read CLAUDE.md so you know the project rules and stack.
2. Read the technical brief so you stay inside its scope.
3. Read the backend builder's summary so you know exactly which
   endpoints exist and what they return.
4. Load the build-with-tests skill for conventions.
5. Look at 2-3 similar components or pages in the codebase and
   match their patterns.

Implementation rules:

- Only edit frontend files: components, pages, hooks, client-side helpers, and their tests.
- Never edit services, API routes, workers, or migrations. That
  is the backend-builder's job.
- Consume the API exactly as the backend builder produced it.
  If the shape is wrong for the UI, surface the mismatch as
  feedback instead of patching around it.
- Match existing component patterns. Styling, accessibility,
  loading states, and error handling should look like the rest
  of the codebase.
- Do not refactor unrelated code.
- Do not add new dependencies without explicit instruction.
- Write component or unit tests alongside the production code.

After you edit:

1. Run the project's typecheck, lint, and test commands (from
   CLAUDE.md).
2. Confirm all tests pass.
3. Return a short summary:
   - Files added / edited (frontend only)
   - Patterns and components reused
   - Anything you noticed that would benefit from a CLAUDE.md
     rule

If you cannot complete the work without violating one of the
rules above, stop and report the conflict.

Agent 6: Test-Verifier

Once the feature is built end to end, the test verifier writes acceptance tests that exercise the user story directly. Unit tests live next to the code they cover (the build agents wrote them). Acceptance tests live here. They are how the chain proves the feature actually does what the story said it should.

Create a project-level subagent named test-verifier.

Its job: given the approved user story, the approved technical
brief, and a feature that has already been built end to end,
write acceptance tests that exercise the user story and confirm
each acceptance criterion holds.

Inputs:
- the approved user story (with acceptance criteria)
- the approved technical brief
- the backend builder's and frontend builder's summaries
- the build-with-tests skill (project skill)

Outputs:
- one acceptance test file (or one extension of an existing
  one) that covers every acceptance criterion in the story
- a short report of which criteria are covered and which are
  not (only if any are missing or untestable)

Tool access: Read, Edit, Write (test files only), Bash.
Recommended model: sonnet.
Recommended color: yellow.

Behaviour rules:
- Read the user story and the brief before writing.
- Use the build-with-tests skill for conventions.
- Cover every acceptance criterion, plus the edge cases listed
  in the story.
- Do not modify backend or frontend files outside the test
  folder.
- After writing, run the new tests once. Report pass/fail and
  any acceptance criterion that could not be covered cleanly.

Claude responds:

I have created the agent at .claude/agents/test-verifier.md with the following content. The agent is scoped to test files only. It uses the build-with-tests skill for conventions and runs after both build agents have finished, so it has a working feature to test against.

---
name: test-verifier
description: Writes acceptance tests against the user story after the build agents have finished. Confirms every acceptance criterion holds against the built feature. Uses the build-with-tests skill. Run after backend-builder and frontend-builder.
tools: Read, Edit, Write, Bash
model: sonnet
color: yellow
---

You are the acceptance test author for this project. Your job is to verify, with tests, that the feature now built end to end
actually satisfies every acceptance criterion in the user story.
 
Before writing:

1. Read the approved user story so you know every criterion.
2. Read the approved technical brief so you know how the
   feature is wired together.
3. Read the backend builder's and frontend builder's summaries
   so you know which endpoints, components, and behaviours exist.
4. Load the build-with-tests skill for conventions.
5. Look at 2-3 existing acceptance tests in the codebase and
   match their style.

Writing rules:

- Cover every acceptance criterion in the user story.
- Cover the edge cases the story lists.
- Use the project's test data builders, not inline setup.
- Follow the project's existing acceptance-test layout.
- Edit only test files. Do not edit any code.

After writing:

1. Run the new tests.
2. If any fail, the feature does not satisfy the story. Report
   exactly which criterion failed and why. Do not patch the
   code. That is for the build agents to fix on the
   next loop.
3. If any criterion cannot be covered cleanly (for example, the
   brief did not name a way to observe it), report it. Do not
   invent a workaround.
4. Return a short summary: criteria covered, criteria failed,
   criteria that need clarification.

Agent 7: Implementation-Validator

Compares the current state of the implementation against the approved story and brief. Reports gaps. Never fixes them. The validator is the agent that catches everything the build agents and test verifier missed.

Create a project-level subagent named implementation-validator.

Its job: compare the current implementation against the approved user story and technical brief, and report gaps. It does not fix anything.

Inputs:
- the approved user story
- the approved technical brief
- the current state of the implementation (files on disk)
- the test verifier's report

Outputs, grouped by severity:
- critical (must fix before merge)
- important (should fix before merge)
- minor (nice to have)
- recommended next agent

Always check for:
- missing acceptance criteria
- missing tests for failure paths
- security issues (auth checks, tenant isolation, raw error
  exposure, secrets in logs)
- changes to files outside the agreed scope
- inconsistent project patterns (compared to CLAUDE.md and
  existing code)
- duplicate logic that should be reused
- timezone or multi-tenant concerns from the brief that the
  implementation may have missed

Tool access: Read, Grep, Glob.
Recommended model: sonnet (this needs careful reasoning).
Recommended color: red.

Behaviour rules:
- Never edit files.
- Never run destructive commands.
- Always cite the file and line number for each finding.
- If a finding is opinion-based rather than a real risk,
  mark it as such.

Claude responds:

I have created the agent at .claude/agents/implementation-validator.md with the following content. Restart your Claude Code session to load it. You can then invoke it as @implementation-validator once the chain has produced an implementation to review.

---
name: implementation-validator
description: Strict reviewer that compares the current implementation against the approved user story and technical brief and reports gaps grouped by severity. Never edits files. Use after the build and verification agents have finished, before opening a PR.
tools: Read, Grep, Glob
model: sonnet
color: red
---

You are an implementation validator for this project. Your only
job is to compare the code on disk against the approved user
story and technical brief, and report what is missing or wrong.
You do not fix anything.

Inputs you should expect:

- The approved user story.
- The approved technical brief.
- The current state of the implementation (files on disk).
- The test verifier's report.

What to check, every time:

- Acceptance criteria from the story that are not implemented.
- Failure paths from the brief that have no test coverage.
- Security issues: missing auth checks, tenant isolation gaps,
  raw error exposure, secrets in logs, missing rate limits on
  sensitive endpoints.
- Changes to files outside the agreed scope.
- Inconsistencies with project patterns documented in CLAUDE.md
  or visible in the existing codebase.
- Duplicate logic that should reuse existing helpers.
- Timezone or multi-tenant concerns called out in the brief
  that the implementation may have missed.

Output format, every time:

**Critical** (must fix before merge)

- <one finding, with file path and line number>
- ...

**Important** (should fix before merge)

- <finding>
- ...

**Minor** (nice to have)

- <finding, marked "(opinion)" if it is opinion-based>
- ...

**Recommended next agent**

- <e.g. "backend-builder to fix tenant isolation in X,
  then test-verifier to add the matching acceptance test">

Behaviour rules:

- Never edit files.
- Never run destructive commands.
- Cite the file and line number for every finding.
- Mark opinion-based findings clearly so reviewers can ignore
  them safely.
- If you find no critical or important issues, say so plainly.
  Do not invent issues to look thorough.

These seven are examples, not the canonical set

Seven agents is enough to ship real features. It is not a ceiling. The whole point of the pattern is that your team builds the agents your team needs, using the anatomy template from earlier in this section. Sky is the limit. Build whatever you want.

A short list of agents you might add next, depending on where your team feels friction:

• accessibility-reviewer: reads new UI code and flags missing labels, contrast issues, keyboard traps, and other problems against your project's standards.

• security-reviewer: runs before the validator and checks for missing auth, tenant isolation gaps, unsafe deserialization, and dependency risks.

• migration-writer: turns a brief's schema change into a Prisma (or your ORM's) migration with the project's naming and rollback conventions.

• design-system-reviewer: checks new components against your design tokens, spacing scale, and existing component library before they ship.

• docs-updater: reads the final diff and updates the README, feature docs, or operator notes from it.

• release-note-writer: reads recent merges and drafts the user-facing change summary in your team's style.

• payments-integration: knows your Stripe webhook conventions inside out, so any engineer can ship a feature that touches billing without a payments specialist on the path.

Each one is the same shape: a focused role, restricted tools, a clear input/output contract, behaviour rules. Use the anatomy template, hand it to Claude with /agents, review the file, commit it. The factory grows the way your codebase grows. Add what you keep doing by hand. Remove what no longer pays for itself.

Start smaller if seven feels like a lot

If standing up seven agents in one weekend feels like too much, do not. The smallest useful version of this pattern is three:

codebase-researcher → build-with-tests skill → implementation-validator

Researcher maps the code. The skill keeps the build agent honest. The validator catches what you missed. Run a few features through that three-piece setup, see where it hurts, then add the next agent that would have prevented the friction. Most teams do not need all seven on day one.

Built-in Subagents You Already Have

Before you build any of the seven above, Claude Code already ships with a few subagents you should know about and use where they fit:

• Explore is read-only and tuned for searching and understanding codebases. Cheap, fast. You can use it directly, or wrap it with your own codebase-researcher when you want a tighter output format.

• Plan gathers context inside plan mode and proposes an implementation plan before any file changes happen.

• General-purpose handles tasks that need both exploration and modification.

Reach for the built-in ones when they fit. Build custom ones when you want a tighter contract on inputs and outputs, or when you want to enforce a specific behaviour rule.

Seven agents is enough to run a real factory. The eighth piece, the one that makes them work together, is the orchestrator in the next section.

7. The Workflow Layer: The Orchestrator That Runs the Chain

You now have seven agents that each do one thing well. The next question is: who decides when to call which agent, and in what order?

In a vibe-coding workflow, the answer is "the human types prompts." That works, but it makes the human the orchestrator. You hold the chain in your head. You remember to call the researcher first. You remember to pause for review. You remember to invoke the validator at the end. Miss one step and the chain breaks.

The whole point of a factory is that the chain runs itself. The human stays in the loop where judgement matters (approving the story, approving the brief, approving the PR), but the routing between agents is automated.

That is what an orchestrator does.

What The Orchestrator Is

The orchestrator is another piece of the factory whose only job is to delegate to other agents in the right order, pass the right inputs forward, pause for human approval at the right points, and recover when an agent reports a problem.

There are a few ways to build it in Claude Code. I will show you two.

1. As a skill or a slash command. This is the starter version. Either a SKILL.md file at .claude/skills/feature-factory/SKILL.md (auto-triggers when its description matches what you ask) or a Markdown file at .claude/commands/feature-factory.md (runs when you type /feature-factory). Same content in either, different way of firing it. Simple, no new concepts, easy to read and edit.

2. As a subagent. This is the advanced upgrade. It runs in its own context window and can delegate to the other seven agents using Claude Code's subagent invocation. Cleaner, more powerful, but it adds one more concept on top.

Build the skill/command version first. Live with it for a week. Then upgrade to the agent version when you understand the chain well enough to want stronger automation.

The Chain Itself

Here is the chain the orchestrator runs.

There are three human approval points:

1. After the story. Is this the right problem? Are the acceptance criteria correct?

2. After the brief. Is the design safe? Any red flags before code is written?

3. After validation. Is this PR ready to ship?

Everything else is the orchestrator routing work between agents.

Version 1: The Orchestrator as a Skill

Create a skill at .claude/skills/feature-factory/SKILL.md. Ask Claude to generate it for you:

Create a Claude Code skill at .claude/skills/feature-factory/SKILL.md that orchestrates a feature build using seven existing subagents: codebase-researcher, story-writer, spec-writer, backend-builder, frontend-builder, test-verifier, implementation-validator.

The skill should:
- Trigger when the user asks to build, ship, or implement a
  feature with phrases like "build a feature", "ship a
  feature", "feature factory", "run the full chain".
- Run the chain in the order described below.
- Pause for human approval after the story and after the brief.
  At each approval point, handle three outcomes: approved,
  changes requested, or rejected.
- Run backend-builder first, then frontend-builder, then
  test-verifier.
- Invoke implementation-validator at the end and report
  critical, important, and minor findings.
- If the validator reports critical gaps, loop back to the
  appropriate builder (backend or frontend), then re-run
  test-verifier and the validator.

Order:
1. codebase-researcher: map the area of code involved.
2. story-writer: produce a user story.
3. ASK HUMAN: approve the story.
   - Approved: continue.
   - Changes requested: re-invoke story-writer with the human's
     feedback. Repeat this step until approved or rejected.
   - Rejected: stop the chain. Summarise what was explored so
     the human can decide what to do next.
4. spec-writer: produce a technical brief.
5. ASK HUMAN: approve the brief.
   - Approved: continue.
   - Changes requested: re-invoke spec-writer with the human's
     feedback. Repeat this step until approved or rejected.
   - Rejected: stop the chain. Keep the approved story so the
     human can resume later with a different technical
     approach.
6. backend-builder: implement backend + unit tests.
7. frontend-builder: implement frontend + component tests.
8. test-verifier: write acceptance tests against the story.
9. implementation-validator: report findings.
10. If critical findings: route back to backend-builder or
    frontend-builder, then re-run test-verifier and the
    validator.
11. ASK HUMAN: final review before opening PR.

Show me the skill file before saving it.

Claude will produce something like this:

---
name: feature-factory
description: Use this skill when the user asks to build, ship,
  or implement a feature end to end. Runs the full chain of
  seven subagents with human approval points after the story
  and the brief, runs the build agents in order (backend,
  frontend, test-verifier), then validates. Triggers on:
  "build a feature", "ship a feature", "run the factory",
  "feature factory".
---

Process:

1. Invoke the codebase-researcher subagent. Pass the feature
   idea and the relevant area of code. Wait for findings.

2. Invoke the story-writer subagent. Pass the feature idea
   and the researcher's findings. Wait for the user story.

3. Show the story to the user. Ask: "Does this match what
   you want? Reply 'approved' to continue, describe what
   to change, or reply 'reject' to stop the chain."
   - If approved, continue.
   - If changes requested, invoke story-writer again with
     the user's feedback. Repeat this step until approved
     or rejected.
   - If rejected, stop the chain. Summarise what was
     explored so the user can decide what to do next.

4. Invoke the spec-writer subagent. Pass the approved story
   and the researcher's findings. Wait for the technical brief.

5. Show the brief to the user. Ask: "Any design red flags?
   Reply 'approved' to continue, describe what to change,
   or reply 'reject' to stop the chain."
   - If approved, continue.
   - If changes requested, invoke spec-writer again with
     the user's feedback. Repeat this step until approved
     or rejected.
   - If rejected, stop the chain. Keep the approved story
     so the user can resume later with a different
     technical approach.

6. Invoke the backend-builder subagent. Pass the brief and the
   researcher's findings. Wait for the backend implementation
   and its summary.

7. Invoke the frontend-builder subagent. Pass the brief, the
   researcher's findings, and the backend builder's summary
   (so it knows the API contract). Wait for the frontend
   implementation and its summary.

8. Invoke the test-verifier subagent. Pass the approved story,
   the brief, and both builder summaries. Wait for the
   acceptance tests and the verifier's report.

9. Invoke the implementation-validator subagent. Pass the
   approved story, the approved brief, the test verifier's
   report, and the current implementation. Wait for findings.

10. If the validator reports critical findings, route them to
    the right build agent (backend-builder or frontend-builder)
    along with the relevant test from test-verifier. Then
    re-run test-verifier and the validator.

11. Show the validator findings to the user. Ask:
    "Ready to open the PR?"

Rules:

- Never skip the human approval points.
- Never invoke frontend-builder before backend-builder.
- Never invoke test-verifier before both builders have
  finished.
- Never invoke the validator before the chain has produced
  some implementation and the verifier has run.
- Each agent runs in its own subagent context. Pass only
  the inputs that agent needs.
- If any agent reports it cannot complete its task, stop
  and surface the reason to the user.

That is the full orchestrator. It is a single Markdown file. It calls seven other Markdown files. Together they are a factory. Now you might thinking what if we have to create only backend endpoint not frontend or vice versa. So that totally depends on your needs. Create in that specific way. Above are just examples. You have to decide what you want to build.

Running the Chain: A Compact End-to-End Example

You open Claude Code and type:

/feature-factory

I want to add reminder emails for invoices that have been unpaid for more than 7 days.

What happens next, step by step:

Step 1. The orchestrator delegates to codebase-researcher. The researcher runs in its own context, reads the invoice, payment, and email files, and returns:

Invoices are created in services/invoices/create.ts. Status is stored on the Invoice model. Transactional email goes through services/email/send.ts using Resend templates. BullMQ workers in workers/ already handle scheduled jobs. No existing reminder logic. Admin UI lives under app/(admin)/invoices/. Likely files to change: Invoice model, a new reminder service, the email template registry, a new admin page for manual triggers.

Step 2. The orchestrator delegates to story-writer, passing the feature idea and the findings. It returns:

As an account admin, I want overdue invoice reminders to be sent automatically, so customers are reminded without manual follow-up.

Acceptance criteria:

1. A reminder is sent when an invoice is unpaid for more than 7 days.

2. No reminder is sent for paid invoices.

3. Duplicate reminders are not sent in the same window.

4. Failed email attempts do not mark the reminder as sent.

5. Admins can see when the last reminder was sent.

6. Admins can manually trigger a reminder for a specific invoice.

Edge cases: invoice exactly 7 days old, retries, tenant isolation, timezone. Out of scope: SMS reminders, customer-side preferences.

Step 3. The orchestrator pauses and offers three options: approve, request changes, or reject. You read the story. It matches what you want, so you approve.

Step 4. The orchestrator delegates to spec-writer, passing the approved story and the researcher's findings. It returns a brief: data model change (lastReminderSentAt), BullMQ flow, admin endpoint for manual trigger, admin UI tile showing last sent time, tests required, risks (multi-tenant, timezone).

Step 5. You read the brief. You notice it says "we will store processed invoice IDs in memory." Red flag. You reply:

Change the deduplication approach. Do not use in-memory state.
Use the lastReminderSentAt column instead.

The orchestrator re-invokes spec-writer, the brief is updated, you approve.

Step 6. The orchestrator delegates to backend-builder, passing the brief and the researcher's findings. The builder adds lastReminderSentAt to the Invoice model, writes the new reminder service, plugs it into the existing BullMQ worker, adds an admin endpoint for manual triggers, and writes unit tests for each. Runs typecheck, lint, and the test suite. All green. Returns a summary:

Backend implementation complete.

Files added:

• services/reminders/send-overdue.ts

• app/api/admin/invoices/[id]/remind/route.ts

• workers/reminders.worker.ts

Files edited:

• prisma/schema.prisma (added lastReminderSentAt column)

Reused: prisma, sendEmail, daysAgo, existing invoice-reminder email template, existing BullMQ redisConnection. Tenant isolation enforced in the manual-trigger endpoint via the existing requireSameTenant helper.

Unit tests added: 7. All passing. Suggested CLAUDE.md rule: "Reminder columns follow the last<Action>SentAt pattern."

Step 7. The orchestrator delegates to frontend-builder, passing the brief, the researcher's findings, and the backend builder's summary. The frontend builder reads the API contract from the summary, adds a "Last reminder sent" column to the admin invoice table, adds a "Send reminder" button on each row that posts to the manual-trigger endpoint, handles loading and error states, and writes component tests. Runs typecheck, lint, and the test suite. All green. Returns a summary:

Frontend implementation complete.

Files added:

• app/(admin)/invoices/_components/ReminderColumn.tsx

• app/(admin)/invoices/_components/SendReminderButton.tsx

Files edited:

• app/(admin)/invoices/page.tsx (added column and button)

Reused: existing admin DataTable, existing useMutation hook for the API call, existing Toast for success/error states. API consumed exactly as the backend summary documented.

Component tests added: 5. All passing.

Step 8. The orchestrator delegates to test-verifier, passing the approved story, the brief, and both builder summaries. The verifier writes one acceptance test file covering all six acceptance criteria plus the edge cases. Runs the new tests. Reports:

Acceptance tests written: 8 (one per acceptance criterion plus two edge cases).

7 passing. 1 failing: "manual trigger is rejected across tenants" returns 200 instead of 403. Looks like the admin endpoint is not checking tenant before sending. Recommending the validator confirm.

Step 9. The orchestrator delegates to implementation-validator. The validator returns:

Critical: the manual trigger endpoint does not check that the admin belongs to the same tenant as the invoice. A Company A admin can trigger a reminder for a Company B invoice. (app/api/admin/invoices/[id]/remind/route.ts, line 14.) The requireSameTenant helper is imported but never called.

Important: no test covers the case where lastReminderSentAt is exactly 7 days ago. Clarify whether the rule is > or >=.

Minor: the new ReminderColumn could reuse the existing RelativeTime component instead of inlining its own formatter.

Step 10. Critical finding detected. The orchestrator loops back. It delegates to backend-builder with the validator's finding and the failing acceptance test from the verifier. Backend builder fixes and calls requireSameTenant in the manual-trigger endpoint, re-runs unit tests. Then the orchestrator re-runs test-verifier. All eight acceptance tests pass. Then implementation-validator runs again. Clean.

Step 11. The orchestrator pauses for your final review and asks if you want it to open the PR.

That is a working factory. One prompt kicked it off. Seven agents did the focused work. The orchestrator routed the chain and paused at the three points where your judgement was needed.

Version 2: The Orchestrator as a Subagent (Advanced)

Once you have lived with the skill version for a while, you may want the orchestrator to run in its own context window. The skill version inherits your main session's context. That can be fine for short features, but for longer ones the main context fills up with the chain's intermediate state.

Promoting the orchestrator to a subagent gives it isolation. Type /agents and use this description:

Create a project-level subagent named feature-orchestrator.

Its job: take a feature idea from the user and run the full
seven-agent chain (codebase-researcher, story-writer, spec-writer, backend-builder, frontend-builder, test-verifier,
implementation-validator), pausing for human approval after the
story and after the brief, running the build agents in order
(backend then frontend then verifier), then validating, then
looping back to the right build agent if the validator finds
critical gaps. Use the feature-factory skill for the exact step
order, including the approve, changes-requested, and rejected
paths at each human approval point.

Inputs:
- a rough feature idea from the user

Outputs:
- a finished implementation in the working directory
- a final summary of what was built, tests added, and any
  validator findings the human chose to waive at the final
  review

Tool access: Task (to invoke other subagents), Read, Bash.
Recommended model: sonnet (this needs reasoning for routing).
Recommended color: gray.

Behaviour rules:
- Use the feature-factory skill as the canonical step order.
- Always invoke other agents through subagent invocation, not
  by inlining their work.
- Always pause at the human approval points described in the
  skill. At each approval point, handle approved, changes
  requested, and rejected paths exactly as the skill defines.
- If any agent fails, surface the failure with the agent name
  and stop. Do not silently retry.
- Never edit code directly. Always go through the
  appropriate build agent.

The behaviour is almost identical to the skill version. The only difference is that the orchestrator now runs in its own context. You invoke it with @feature-orchestrator and a feature idea. The orchestrator's context is preserved across the chain. Your main session stays clean.

Pick one version. Run a few real features through it. The factory will reveal where it needs tuning according to your codebase.

Why This Works

Each step reduces a different kind of ambiguity. The story reduces business ambiguity. The brief reduces technical ambiguity. The backend builder reduces API ambiguity. The frontend builder reduces UI ambiguity. The test verifier proves the user story actually holds. The validator catches what everyone else missed. By the time the chain reaches the validator, the feature has been constrained by everything that came before it. The validator only has to check the gap between what the brief asked for and what the code does.

The orchestrator turns that chain from "a workflow you remember to run" into "a workflow that runs itself, with you in the loop only where it matters."

This is the move from vibe coding to factory thinking, and it is the single biggest mindset change in this whole article.

Extending the Chain

Seven agents and three human approval points are a starting point, not a ceiling. Once your basic chain is running, you can add more agents wherever you want extra rigour. A security reviewer that runs before the validator. A performance auditor that flags slow queries on the new code paths. A docs writer that updates the README from the diff. A migration reviewer that sanity-checks any Prisma changes before they merge. The pattern is the same every time: define the agent using the anatomy template, restrict its tools, plug it into the orchestrator's step order, decide whether the human needs to review its output.

You can also move some of the human approval points into agents if your team trusts them. The story approval is hard to remove because business intent is genuinely a human call. The brief approval can sometimes be replaced by a second spec-reviewer agent for low-risk features. The final PR approval should always stay human.

A factory grows the way a real codebase grows. Start small. Add what your team keeps doing by hand. Remove what no longer pays for itself.

Run Reads in Parallel, Run Writes in Sequence

One last design rule that saves a lot of pain.

Read-only agents can run in parallel. They do not touch the files on disk, so two or more of them running at the same time cannot conflict. Running them in parallel is one of the easiest speed-ups you will get from this whole setup. For example, say you maintain four services and you need to refresh the docs for each one before a quarterly review. You can fire four codebase-researcher subagents in parallel, one per service. Each one reads its own codebase, summarises what changed, and returns its findings independently. Then four docs-updater agents pick up the findings, one per service, and rewrite each README in parallel. Because each docs-updater works on a different repo, they cannot collide on the same files. Four parallel reads, four parallel writes, and a job that used to drag on now finishes quickly.

Write agents (backend-builder, frontend-builder, test-verifier) must run in sequence. They edit files. If two of them touch the same file at the same time, you get partial writes, lost edits, broken tests, and a confused git status. Worse, the failure is silent until you notice the diff is wrong, and tracing back to which agent wrote what becomes its own debugging job.

The orchestrator handles this for you when you set it up correctly. Inside the build phase, backend-builder always finishes before frontend-builder starts, and frontend-builder always finishes before test-verifier starts. Outside the build phase, parallel reads are fair game.

Rule of thumb: anything with Read, Grep, or Glob access only is safe to run in parallel. Anything with Edit, Write, or Bash access must run alone in its lane.

Failure Modes to Expect

Every team running a chain like this hits the same handful of issues in the first couple of weeks. None of them break the factory. Here is what to watch for, with a quick fix for each.

• Orchestrator skips a human approval. Make the approval step explicit in the skill or agent (ASK HUMAN: approve the story).

• An agent silently summarises away part of its work. Add a "what was covered / what was skipped" checklist to its output format.

• Validator misses something a human reviewer caught later. Add a new rule to the validator's behaviour rules. The validator gets sharper feature by feature.

• Session runs out of context mid-chain. Keep CLAUDE.md tight and start a fresh main session for each major feature.

• Chain runs perfectly but the spec misunderstood the business rule. This is exactly why the story approval is a hard human checkpoint.

• Frontend builder invents an endpoint the backend builder did not produce. Strengthen the frontend builder's rule to consume the backend summary exactly. Surface mismatches as feedback, not as patches.

A good factory makes mistakes easier to catch, not harder to see.

8. The Delivery Layer: PRs, Reviews, and the New SDLC

So far this article has been close to the keyboard. Let's zoom out.

When AI absorbs much of the coding, testing, and documentation work, the cost of producing a software change drops. That does not mean software becomes free. It means the bottleneck moves. The slow part used to be typing, wiring, and searching. The slow part now is choosing the right feature, defining the right constraints, validating behaviour, and deciding what should ship.

That changes how teams are organized, how reviews are done, and how delivery pipelines work.

Figure 6: How the SDLC reshapes when the orchestrator absorbs the coding work. Handoffs collapse. Review and judgement stay human.

One Engineer can now Finish a Complete Vertical Slice

The shape of the SDLC changes when the chain runs the heavy lifting.

Before, a feature moved through a queue of specialists. A frontend engineer who needed a new API endpoint waited for a backend engineer. A backend engineer who needed a UI waited for a frontend engineer. A new feature might pass through three or four people before it shipped, and most of that time the work was sitting still in someone's review queue.

Now, the same engineer kicks off /feature-factory, the chain runs end to end (backend, frontend, acceptance tests, validation), and a complete vertical slice lands as one PR. One person on the path. Zero handoffs. Section 11 returns to this and explores what it means for the team and for the wider industry. For now, what matters is that the unit of work has changed: features come out of the chain whole, not piecemeal.

Stack Your Features, not the Inside of one Feature

Once handoffs are gone, the next question is "what do I do while my last PR is in review?" The answer is the second feature. And the third.

The pattern that fits this is stacked PRs, but the unit of stacking is one PR per feature, not one PR per slice of a feature. Each PR is a complete vertical slice produced by one chain run.

It looks like this in practice. You finish Feature A. You open PR A from feature-a against main. While A is waiting for review, you do not stop. You branch feature-b on top of feature-a (not on top of main), kick off /feature-factory for the next feature, and ship PR B against feature-a. While both A and B are in review, you branch feature-c on top of feature-b and start the third one.

The order matters. A has to merge first. Then B rebases onto main and merges. Then C rebases onto main and merges. Tools like Graphite, Sapling, or git's own git rebase --onto handle the rebasing automatically when an upstream PR merges. You do not need to think about it most of the time.

Two rules keep this safe.

First, respect the chain. If C depends on B, do not try to merge C before B. The branch graph already enforces this, but it is worth saying out loud because the temptation to skip ahead is real when an early PR is taking too long to review.

Second, do not split one feature across the stack. A single feature should be one PR. If you find yourself wanting to put the migration in PR 1, the backend in PR 2, and the UI in PR 3, that usually means the chain produced too much in one run. Go back, split at the story level (Section 7), and run two smaller chains instead. Each chain still produces one feature, and each feature still ships as one PR.

The factory's whole point is that one engineer can finish a feature without waiting for anyone. Stacked PRs are how you keep that going across multiple features without blocking yourself on your own review queue.

This is where the software industry is heading. Smaller teams, fewer handoffs, every engineer shipping complete features end to end. The teams that get there first will not be the ones with the best AI tools. They will be the ones who built the cleanest factories around the AI tools they already have.

Add a PR Reviewer Agent

A team using AI needs a PR review pattern that is consistent across both human and AI reviewers. The single most useful artifact for that consistency is a short, explicit checklist that every PR is reviewed against. Without it, review becomes subjective. With it, everyone checks for the same things every time.

I covered AI-assisted PR review in detail in my previous article on unblocking the AI PR review bottleneck, including the full checklist I use, the rules that work, and the ones that quietly do not. If you have not read it, do that next. The factory you just built is the upstream half of that workflow. PR review is the downstream half.

For the factory specifically, the cleanest place to put the checklist is inside another agent. Use the /agents slash command and create a pr-reviewer agent the same way you created the seven in Section 6:

Create a project-level subagent named pr-reviewer.

Its job: review a pull request against this project's review
checklist and report findings grouped by severity. It does
not edit files or merge PRs.

Inputs:
- a PR or a diff to review
- CLAUDE.md and any project-level rules

Outputs, grouped by severity:
- critical (must fix before merge)
- important (should fix before merge)
- minor (nice to have)

Always check for:
- Scope: one clear purpose, no unrelated refactoring,
  no unrelated files.
- Tests: unit tests cover the core behaviour, failure
  cases tested, existing tests still pass.
- Security and tenant safety: auth checks, tenant isolation
  preserved, no secrets in logs or error responses.
- Architecture: business logic out of UI and API route
  handlers, existing patterns from CLAUDE.md respected,
  no unjustified new dependencies.
- Documentation: README or feature docs updated for
  user-facing changes, technical debt acknowledged in
  the PR description.

Tool access: Read, Grep, Glob, Bash (for git commands only).
Recommended model: sonnet (this needs careful reasoning).
Recommended color: orange.

Behaviour rules:
- Never edit files.
- Never merge or close PRs.
- Cite file paths and line numbers for every finding.
- Mark opinion-based findings clearly so reviewers can
  ignore them safely.

Claude generates the file, you review and commit it, and now your project has a consistent reviewer that humans and AI invoke the same way: @pr-reviewer review this PR. You can also wire it into your CI pipeline so every developer handles their own PR feedback before a human reviewer ever sees it. The load on reviewers drops.

This pattern matters because the agent becomes the single source of truth. Humans read its findings before merging. The orchestrator from Section 7 can invoke it as the final step before opening a PR. CI can run it on every push. The checklist lives in one place and updates in one place. When your team learns a new failure mode, you add it to the agent's behaviour rules, and the next review picks it up automatically.

Cloud Reviewers are Functions, not Colleagues

AI is starting to live inside CI pipelines: PR review bots, security scanners, release-note generators, issue triagers. That is genuinely useful. But the language matters.

If you say "Claude approved this PR," you have already made a small mistake. Cloud-based AI is not a teammate. It is not a developer. It is not accountable for the decision. The right sentence is "Claude ran the review workflow against the project's review checklist and reported findings, and a human decided the PR was safe to merge." Accountability stays with the human.

There is a practical reason for this discipline. Cloud reviewers are good at the things they were prompted to look for: missing tests, naming inconsistencies, duplicate helpers. They miss things outside their checklist. If your checklist does not specifically tell the reviewer to verify tenant isolation in invoice download endpoints, the AI reviewer might still let through a bug where a user from Company A can download an invoice from Company B. That is why a project-specific review checklist is so much more valuable than a generic AI reviewer.

Where Humans Win

AI review is not approval. AI can help find issues. It can summarize complex changes. It can compare code against a checklist. It can suggest tests. But humans still own the decisions that matter: does this solve the right problem, is this an acceptable trade-off, should it ship now, should it ship behind a feature flag, do we need more user data first?

That judgement is still human work. The best AI-assisted teams are not the ones that remove humans. They are the ones that put humans where their judgement matters most.

9. Build Your First Claude-Powered Software Factory

Theory is done. Here is the checklist to stand up the factory in your own project. Each step points back to the section that explains the why.

Total time: two to three hours for the first version.

When You Run the First Real Feature

Pick something small. An admin tool, a new API endpoint with a tiny UI tile. Open Claude Code:

/feature-factory

I want to <describe the feature in one sentence>.

The chain will run. Approve the story. Approve the brief. Read the validator report. Open the PR.

The first time will not be perfect. Things to note as you go:

• Researcher's output too shallow? Strengthen its description.

• Story writer missed an edge case? Add a rule to its description.

• Spec missed a risk? Add the rule to CLAUDE.md.

• Backend builder touched a frontend file? Tighten its scope rule.

• Frontend builder invented an endpoint? Tighten the API-consumption rule.

• Validator missed something a human caught later? Add a check to its rules.

• Hook should have caught something earlier? Add to it.

After three or four features, the factory tunes itself. You will spend less time supervising and more time deciding what to build next.

Part 3: Wrap Up

10. What I Did Not Cover (and Where to Go Next)

AI-assisted development is a huge surface area, and one article cannot cover it all. Here are the topics I deliberately left out, in the order I would explore them next.

Centralized Memory Management Across Sessions

Once you start running multiple sessions in parallel (one per feature, one per branch, one per teammate) you start wishing the AI shared memory across them. Things like Claude's project-level memory, MCP-based shared knowledge stores, and team-wide vector stores fit here. This is a fast-moving area and worth a dedicated read.

Running Agents in Parallel

Claude Code subagents can run in parallel inside a single session. So can multiple sessions across worktrees with tools that wrap Claude Code (Nimbalyst is one example). Once your factory is stable, parallelism gives you the next big speed-up. Be careful with merge conflicts and CI cost.

Cloud-Based Unattended Agents

Running Claude Code or similar agents on a server, triggered by events (a webhook, a cron, a new GitHub issue) lets your factory work while you sleep. The honest state of this in 2026 is that it works for narrow tasks like PR review and triage. It is not yet trustworthy for unattended feature work without strong validation gates.

Custom MCP Servers for Your Business

MCP (Model Context Protocol) lets you expose internal systems like your billing data, your customer support tickets, and your design system to Claude as tools. A well-built MCP server turns Claude from a coding assistant into something closer to a junior teammate who knows your business. Worth a deep look once your basic factory is in place.

Cost Optimization at Scale

Once a team uses this workflow daily, token cost becomes a real budget line. Routing inspection and review to Haiku, reasoning work to Sonnet, and only the heaviest planning to Opus is the simplest lever. Caching, batching, and trimming context are the next ones.

Extending into Product, Design, and Support

This article is developer-focused, but the same shape applies to product owners, designers, and support engineers. They benefit from skills, subagents, and hooks too. The biggest team-level wins come when those roles also build their own corner of the factory and the dev team can call into theirs.

If you want to go deeper, the official Claude Code documentation is the most up-to-date source for subagents, skills, hooks, and MCP. Anthropic also publishes a free introduction-to-subagents course that pairs well with this article.

11. Closing Thoughts

This article opened with a single idea: use AI to automate structured work, not chaotic work. The eleven sections in between are what that looks like in practice.

So before you automate anything, define the system. Write the rules in CLAUDE.md. Generate the skills your team keeps retyping. Create the agents that do focused work. Wire up the orchestrator. Add the gates. And keep humans in the loop where judgement matters, not where typing matters.

A software factory is not a giant autonomous machine that builds your product overnight. It is a small set of files in your repository that turn one developer plus one AI into a controlled team. The agents are the asset. The factory is how you put them to work.

The New Way of Working

Section 8 introduced the idea that one engineer can ship a full vertical slice. Step back from the keyboard for a moment and look at what that means for the team, not just for one developer.

Software has always moved through handoffs. A product owner writes a story, a lead developer turns it into a specification, a backend engineer builds the API, a frontend engineer builds the UI, a payments specialist handles the integration. By the time the feature ships, four or five people have touched it, each waiting for the previous one to finish. Every handoff was time the work spent sitting still.

Figure 7: The old shape. Every arrow is a handoff. Every handoff is a wait.

The factory dissolves most of those handoffs because the expertise is no longer trapped inside the people. It is shared, in the form of agents.

A frontend engineer who has never written a Stripe webhook can still ship a feature that needs one, because the team's payments specialist has already built and tuned a payments-integration agent. A backend engineer who has never built a Recharts dashboard can ship a feature that needs one, because the frontend lead has built a dashboard-component-builder agent. The QA engineer's regression-suite-writer agent is available to everyone. The DevOps engineer's ci-pipeline-updater agent is available to everyone. The security engineer's auth-checker agent runs as part of every chain.

The result is that one engineer can finish a complete vertical slice on their own.

Figure 8: The new shape. Every engineer pulls from the same agent library. Specialists still exist, but their expertise lives in the agents they maintain, not in their availability for handoffs.

Look at what changed. The specialists are still there. The frontend lead still owns the design system. The payments specialist still owns the Stripe integration. The DevOps engineer still owns the CI pipeline. They still bring the taste and judgement that nobody else on the team has. What changed is that their expertise is now portable. It rides inside agents that anyone on the team can invoke.

This shift compounds in three ways:

Cycle time drops. A feature that used to wait for three engineers' time now waits for none. The chain runs end to end for one engineer. The PR opens the same day instead of the same week.

Specialists do their best work. Before, a senior payments engineer spent half their week unblocking other engineers' Stripe integrations. Now they spend that week improving the payments-integration agent itself. The leverage is much higher. One improvement to the agent benefits every feature the team ships from that point on.

Team scaling looks different. Before, hiring a tenth engineer added a tenth set of handoffs. Now, hiring a tenth engineer adds a tenth full-stack contributor who immediately benefits from every agent the existing nine have built. Onboarding speed increases. Coordination cost drops.

This is the broader shift the article is pointing at. The factory is not just a productivity trick for one developer. It is how an engineering team starts to look more like a community of full-stack contributors who share their expertise as code, and less like a relay race where every baton pass costs a day.

The teams that figure this out first will not be the ones with the largest headcount or the biggest AI budget. They will be the ones whose agent libraries reflect their team's collective taste, kept current, kept small, kept tight. The agents are the asset. The factory is how you put them to work.

A Short Note

The shape of this workflow will keep evolving as the tools evolve, and every team has its own way of working. What I have shared here is the smallest version that has actually held up under deadline pressure on real production work. It is not the final word. It is a starting point you can adapt to your team, your stack, and your taste.

If you build a version of this in your own team, I would love to hear what worked and what did not. The fastest way to improve a workflow is to read about other people's failure modes. Good luck building your factory.

Resources

Claude Code

• Claude Code overview: code.claude.com/docs/en/overview

• Subagents: code.claude.com/docs/en/sub-agents

• Skills: docs.anthropic.com/en/docs/claude-code/slash-commands

• Memory and CLAUDE.md: docs.anthropic.com/en/docs/claude-code/memory

• Hooks reference: code.claude.com/docs/en/hooks

• Hooks guide: code.claude.com/docs/en/hooks-guide

Other AI IDEs (the same patterns apply)

• Cursor: cursor.com

• Aider: aider.chat

• Cline: cline.bot

Tools mentioned in the article

• MCP documentation: modelcontextprotocol.io

• Context7 (current docs plugin): context7.com

• Nimbalyst (visual workspace for parallel Claude Code sessions): nimbalyst.com

• Graphite (stacked PRs): graphite.dev

• Sapling (stacked PRs): sapling-scm.com

But despite how central the terminal is to developer workflows, AI assistance there has remained shallow: autocomplete a command here, explain an error there.

That changes when you combine GitHub Copilot CLI with MCP (Model Context Protocol) servers. Instead of an AI that reacts to isolated prompts, you get a terminal that understands your project context, queries live data sources, and chains tool calls autonomously – what the industry is starting to call an agentic workflow.

In this tutorial, you'll learn exactly how to wire these two systems together, step by step. By the end, your terminal will be able to do things like understand your Git history before suggesting a fix, query your running Docker containers before writing a compose patch, or pull live API schemas before generating a request.

Table of Contents

• Prerequisites

• What is GitHub Copilot CLI?

• What is the Model Context Protocol?

• How MCP Servers Work in a Terminal Context

• Step 1 – Install and Configure GitHub Copilot CLI

• Step 2 – Set Up Your First MCP Server

• Step 3 – Wire Copilot CLI to Your MCP Server

• Step 4 – Build a Real Agentic Workflow

• Step 5 – Extend with Multiple MCP Servers

• Debugging Common Issues

• Conclusion

Prerequisites

Before you start, make sure you have the following:

• Node.js v18 or later (node --version)

• npm v9 or later

• A GitHub account with Copilot enabled. The free tier (available to all GitHub users) is sufficient to follow this tutorial. Pro, Business, and Enterprise plans unlock higher usage limits but aren't required.

• GitHub CLI (gh) installed. We'll use it to authenticate.

• Basic familiarity with the terminal and JSON configuration files

• (Optional) Docker installed if you want to follow the Docker MCP example in Step 5

You don't need prior experience with MCP or agentic AI systems, as this guide builds that understanding from the ground up.

What is GitHub Copilot CLI?

GitHub Copilot CLI is the terminal-native interface to GitHub's Copilot AI. Unlike the IDE plugin (which assists with code completion), Copilot CLI is designed specifically for shell workflows. It exposes three main commands:

• gh copilot suggest proposes a shell command based on a natural language description

• gh copilot explain explains what a given command does

• gh copilot alias generates shell aliases for Copilot subcommands

Here's a quick example of suggest in action:

gh copilot suggest "find all files modified in the last 24 hours and larger than 1MB"

Copilot will return something like:

find . -mtime -1 -size +1M

It will also ask if you want to copy it, run it directly, or revise the request. This interactive loop is already useful – but by itself, Copilot CLI has no awareness of your project context. It doesn't know your repo structure, your running services, or your deployment environment. That's where MCP comes in.

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard introduced by Anthropic in late 2024. Its goal is straightforward: give AI models a standardized way to connect to external tools, data sources, and services.

Think of MCP as a universal adapter layer between an AI model and the real world. Without MCP, each AI integration is custom-built: one plugin for GitHub, another for Postgres, another for Slack, all with incompatible interfaces. MCP defines a single protocol that any tool can implement, and any compatible AI client can consume.

An MCP server exposes tools (functions the AI can call), resources (data the AI can read), and prompts (reusable instruction templates). The AI client in our case, a Copilot-powered terminal discovers these capabilities at runtime and uses them autonomously to complete a task.

A few notable MCP servers that are already production-ready:

The full registry lives at github.com/modelcontextprotocol/servers.

How MCP Servers Work in a Terminal Context

Before we get hands-on, it's worth understanding the communication model.

MCP servers run as local processes. They communicate with the AI client over stdio (standard input/output) or over an HTTP/SSE transport. The client sends JSON-RPC messages to the server, and the server responds with structured data.

Here's the simplified flow:

The key word here is grounded. Without MCP, Copilot responds based purely on its training data and your prompt. With MCP, it can call git log --oneline -20 before answering your question about recent regressions and its answer is based on your actual code history, not a generalized assumption.

Step 1 – Install and Configure GitHub Copilot CLI

If you haven't already, install the GitHub CLI:

# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Windows (via winget)
winget install --id GitHub.cli

Then authenticate:

gh auth login

Follow the interactive prompts. Select GitHub.com, then HTTPS, and authenticate via browser when prompted.

Now install the Copilot CLI extension:

gh extension install github/gh-copilot

Verify the installation:

gh copilot --version

You should see output like gh-copilot version 1.x.x.

Optional but recommended: set up shell aliases. This makes the workflow much faster. For bash or zsh:

# Add to your ~/.bashrc or ~/.zshrc
eval "$(gh copilot alias -- bash)"   # for bash
eval "$(gh copilot alias -- zsh)"    # for zsh

After reloading your shell (source ~/.bashrc), you can use ghcs as shorthand for gh copilot suggest and ghce for gh copilot explain.

Step 2 – Set Up Your First MCP Server

We'll start with server-git. It's the most immediately useful for a development workflow and has zero external dependencies.

Install it globally via npm:

npm install -g @modelcontextprotocol/server-git

Test that it runs:

mcp-server-git --version

This server exposes the following tools to any compatible MCP client:

• git_log retrieve commit history with filters

• git_diff diff between branches or commits

• git_status current working tree status

• git_show inspect a specific commit

• git_blame annotate file lines with commit info

• git_branch list or switch branches

Now create a configuration file. MCP clients look for a file called mcp.json to discover available servers. Create it in your project root or in a global config directory:

mkdir -p ~/.config/mcp
touch ~/.config/mcp/mcp.json

Add the following content:

{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--repository", "."],
      "transport": "stdio"
    }
  }
}

A few notes on this config:

• command is the binary to run. Make sure it's on your $PATH.

• args passes --repository . so the server scopes itself to the current working directory.

• transport: "stdio" means communication happens over standard input/output the simplest and most stable option for local servers.

Step 3 – Wire Copilot CLI to Your MCP Server

This is where the two systems connect. GitHub Copilot CLI supports MCP via its --mcp-config flag (available from version 1.3+). You point it at your mcp.json, and Copilot will automatically initialize the declared servers before processing your prompt.

Here's the basic invocation:

gh copilot suggest --mcp-config ~/.config/mcp/mcp.json "why did the build break in the last commit?"

When you run this inside a Git repository, Copilot CLI will:

1. Start the mcp-server-git process

2. Call git_log to retrieve recent commits

3. Call git_diff on the most recent commit

4. Synthesize an answer based on the actual diff output

Try it yourself on a repo with a recent failing commit. The difference in response quality compared to a plain gh copilot suggest is immediately obvious.

Tip: avoid retyping the flag every time. Add a shell function to your .bashrc/.zshrc:

function aterm() {
  gh copilot suggest --mcp-config ~/.config/mcp/mcp.json "$@"
}

Now you just type:

aterm "what changed between main and feature/auth?"

And you're running a fully context-aware, MCP-powered query from a single short command. This function name aterm for agentic terminal is what we'll use throughout the rest of this tutorial.

Step 4 – Build a Real Agentic Workflow

Let's move beyond individual queries and build a workflow that chains multiple tool calls to complete a real developer task: diagnosing a regression.

Imagine you pushed a feature branch and your CI pipeline failed. You don't know exactly which change caused it. Here's how your agentic terminal handles it:

Query 1: understand what changed

aterm "summarize all commits on feature/auth that aren't on main yet"

Copilot calls git_log with branch filters, then returns a structured summary of commits unique to your branch. No copy-pasting SHAs manually.

Query 2: isolate the diff

aterm "show me everything that changed in the auth middleware between main and feature/auth"

This triggers git_diff scoped to the path containing your middleware. Copilot returns the diff with an explanation of what each change does.

Query 3: find the likely culprit

aterm "which of those changes could cause a JWT validation failure?"

At this point, Copilot has the diff in its context window from the previous tool calls. It reasons over the actual code changes not generic knowledge about JWT and pinpoints the likely issue.

Query 4: generate the fix

aterm "write the corrected version of that validation function"

Copilot generates a targeted fix based on the specific code it retrieved via MCP. You get a patch you can directly apply, not a generic code template.

This four-step sequence – understand, isolate, reason, fix – is a complete agentic loop. Each step is grounded in live repository data retrieved through MCP tools. The AI is not hallucinating context. Instead, it's reading your actual codebase.

Step 5 – Extend with Multiple MCP Servers

One MCP server is useful. Multiple MCP servers working together is where the workflow becomes genuinely powerful. Let's add two more: server-filesystem and server-docker.

Install the additional servers:

npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-docker

Update your mcp.json:

{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--repository", "."],
      "transport": "stdio"
    },
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["--root", "."],
      "transport": "stdio"
    },
    "docker": {
      "command": "mcp-server-docker",
      "transport": "stdio"
    }
  }
}

With all three servers active, your terminal can now answer cross-domain questions:

aterm "my Express app container keeps restarting, check the logs and compare with what the healthcheck in my Dockerfile expects"

To answer this, Copilot will:

1. Call docker_logs (server-docker) to pull the container's recent stderr output

2. Call read_file (server-filesystem) to read your Dockerfile

3. Parse the HEALTHCHECK instruction

4. Cross-reference the log errors with the health endpoint path

5. Return a diagnosis explaining the mismatch and suggest the fix

This is an agentic workflow: the model autonomously decides which tools to call, in what order, and synthesizes the results into a coherent answer. You didn't tell it to read the Dockerfile. It inferred that was necessary based on your question.

A note on security: When running server-filesystem, always scope it to a specific directory using --root. Never point it at / or your home directory. Similarly, server-docker has access to your Docker socket run it only in trusted environments.

Debugging Common Issues

mcp-server-git: command not found

The npm global bin directory isn't on your $PATH. Fix:

export PATH="\(PATH:\)(npm bin -g)"
# or for newer npm versions:
export PATH="\(PATH:\)(npm prefix -g)/bin"

Add this line to your .bashrc/.zshrc to persist it.

Copilot CLI doesn't seem to be using MCP tools

Check your Copilot CLI version:

gh copilot --version

MCP support requires version 1.3 or later. Update with:

gh extension upgrade copilot

Also verify your mcp.json is valid JSON a trailing comma or missing bracket will silently prevent server initialization.

MCP server starts but returns no data

Run the server manually to check for errors:

mcp-server-git --repository .

If it exits immediately, check that you're running the command inside a valid Git repository. For server-docker, make sure the Docker daemon is running and your user has access to the Docker socket:

sudo usermod -aG docker $USER
# Then log out and back in

Responses are slow with multiple servers

Each MCP server is a separate subprocess. Spawning several at once adds startup latency, especially on slower machines. Two optimizations:

1. Only declare the servers you actually need for a given project in your mcp.json

2. Use project-specific config files instead of one global config:

# project A (backend)
aterm --mcp-config ./mcp-backend.json "..."

# project B (infra)
aterm --mcp-config ./mcp-infra.json "..."

Conclusion

You've just built an agentic terminal workflow from scratch. Here's a quick recap of what you did:

• Installed and configured GitHub Copilot CLI with shell aliases for fast access

• Set up MCP servers (server-git, server-filesystem, server-docker) and wired them through a mcp.json config

• Created a shell function (aterm) that transparently passes your MCP config to every Copilot query

• Built a multi-step agentic loop for diagnosing regressions using live Git data

• Extended the setup with cross-domain tool orchestration across Git, filesystem, and Docker

The architecture you've built here is not a demo – it's a production-ready pattern. You can extend it with any MCP-compatible server: server-postgres for database-aware queries, server-github for issue and PR context, or custom MCP servers you write yourself for your internal APIs.

The terminal has always been the most powerful surface in a developer's environment. With Copilot CLI and MCP, it's finally becoming an intelligent one.

That is the problem Context Hub is trying to solve.

Context Hub (chub) gives coding agents curated, versioned documentation and skills that they can search and fetch through a CLI. It also gives them two learning loops: local annotations for agent memory and feedback for maintainers.

In this tutorial, you'll learn how the official chub workflow works, how Context Hub organizes docs and skills, how annotations and feedback create a memory loop, and how to build a companion relevance engine that improves retrieval without breaking the upstream content model.

This tutorial uses two public repositories side by side:

• the official upstream project: andrewyng/context-hub

• the companion implementation for this article: natarajsundar/context-hub-relevance-engine

I've also opened a corresponding upstream pull request from my fork to the main project. If you want to track that work from the article, use the upstream pull request list filtered by author: andrewyng/context-hub pull requests by natarajsundar.

What We'll Build

By the end of this tutorial, you'll have:

• a clear mental model for how Context Hub works

• a working local install of the official chub CLI

• a repeatable workflow for search, fetch, annotations, and feedback

• a companion repo that adds an additive reranking layer on top of a Context-Hub-style content tree

• a small benchmark and local comparison UI you can run end to end

• a clear bridge between the companion repo and the smaller upstream PR

Prerequisites

Before you start, make sure you have:

• Node.js 18 or newer

• npm

• comfort with the terminal

• basic familiarity with Markdown

Table of Contents

1. How to Understand Context Hub

2. How to Understand the Official Repo, the Companion Repo, and the Upstream PR

3. How to Install and Use the Official CLI

4. How to Understand Docs, Skills, and the Content Layout

5. How to Use Incremental Fetch and Layered Sources

6. How to Use Annotations and Feedback to Create a Memory Loop

7. How to See Where Relevance Still Misses

8. How the Companion Relevance Engine Improves Retrieval

9. How to Run the Companion Repo End to End

10. How to Read the Benchmark Honestly

11. How to Connect the Companion Repo to the Upstream PR

12. Conclusion

13. Sources

How to Understand Context Hub

Context Hub is easiest to understand as a workflow for turning fast-moving documentation into a reliable input for coding agents.

Instead of asking an agent to rely on whatever it remembers from training data, you give it a predictable contract:

1. search for the right entry

2. fetch the right doc or skill

3. write code against that curated content

4. save local lessons as annotations

5. send doc-quality feedback back to maintainers

That system boundary matters.

It makes the agent easier to audit, easier to improve, and easier to extend. It also keeps the interface small enough that you can reason about where the failures happen. If the agent still misses the answer, you can ask whether the problem happened during search, fetch, context selection, or generation.

How to Understand the Official Repo, the Companion repo, and the Upstream PR

This tutorial is intentionally split across two codebases and one contribution path.

The official upstream project, andrewyng/context-hub, is the source of truth for the real CLI, the content model, and the documented workflows. That's the codebase you should use to learn how chub works today.

The companion repository, natarajsundar/context-hub-relevance-engine, is where the relevant ideas in this article are made concrete. It's a companion implementation, not a replacement product. Its job is to make retrieval tradeoffs visible, measurable, and easy to run locally.

The upstream PR is the bridge between those two worlds. The companion repo is where you can iterate faster on benchmarks, reranking, and the comparison UI. The upstream PR is where the smallest reviewable slices can be proposed back to the main project. You can track that thread here: upstream PR search filtered by author.

That three-part framing keeps the article honest:

• use the upstream repo to understand the current system

• use the companion repo to explore relevant improvements end to end

• use the upstream PR to show how a larger idea can be broken into reviewable pieces

How to Install and Use the Official CLI

The official quick start is intentionally small.

npm install -g @aisuite/chub

Once the CLI is installed, you can search for what is available and fetch a specific entry:

chub search openai
chub get openai/chat --lang py

That's the happy path, but it helps to think through the request flow.

In practice, the most useful detail is that the CLI is designed for the agent to use, not just for the human to use by hand.

That's why the upstream CLI also ships a get-api-docs skill. For example, if you use Claude Code, you can copy the skill into your local project like this:

mkdir -p .claude/skills
cp $(npm root -g)/@aisuite/chub/skills/get-api-docs/SKILL.md \
  .claude/skills/get-api-docs.md

That step teaches the agent a retrieval habit:

Before you write code against a third-party SDK or API, use chub instead of guessing.

That behavioral rule is often as important as the docs themselves.

How to Understand Docs, Skills, and the Content Layout

Context Hub separates content into two categories:

• docs, which answer “what should the agent know?”

• skills, which answer “how should the agent behave?”

That distinction makes the content model easier to scale. Docs can be versioned and language-specific. Skills can stay short and operational.

The directory structure is also predictable. The content guide organizes entries by author, then by docs or skills, then by entry name.

A small example looks like this:

author/docs/payments/python/DOC.md
author/docs/payments/python/references/errors.md
author/skills/login-flows/SKILL.md

This is one of the reasons Context Hub is easy to work with.

The shape of the content is plain Markdown, the main entry file is predictable, and the build output is inspectable. You don't have to reverse engineer a hidden prompt layer to figure out what the agent is reading.

How to Use Incremental Fetch and Layered Sources

One of the best design choices in Context Hub is that it doesn't force you to inject every file into the model on every request.

Instead, the entry file gives you the overview, and the reference files hold the deeper material.

That lets you fetch content in progressively larger slices.

chub get stripe/webhooks --lang py
chub get stripe/webhooks --lang py --file references/raw-body.md
chub get stripe/webhooks --lang py --full

This is a token-budget feature as much as it is a documentation feature. A good agent should first load the overview, decide what part of the task matters, and only then fetch the specific supporting file.

Context Hub also supports layered sources. You can merge public content with your own local build output through ~/.chub/config.yaml.

A minimal configuration looks like this:

sources:
  - name: community
    url: https://cdn.aichub.org/v1
  - name: my-team
    path: /opt/team-docs/dist

That means you can keep public docs in one lane and team-specific runbooks in another lane while still giving the agent one search surface.

How to Use Annotations and Feedback to Create a Memory Loop

Context Hub has two different improvement channels.

Annotations are local. They help your agent remember what worked last time. Feedback is shared. It helps maintainers improve the docs for everyone.

That distinction matters because not every lesson belongs in the shared registry. Some lessons are environment-specific. Others point to content quality issues that should be fixed centrally.

Here is what local memory looks like in practice:

chub annotate stripe/webhooks \
  "Remember: Flask request.data must stay raw for Stripe signature verification."

And here's the feedback path:

chub feedback stripe/webhooks up

That loop is simple, but it's one of the most important ideas in the project. It turns a one-off debugging lesson into either persistent local memory or a signal that the shared docs need to improve.

How to See Where Relevance Still Misses

The upstream project already has a real ranking story. It uses BM25 and lexical rescue so that package-like identifiers, exact tokens, and fuzzy matches still have a chance to surface.

That is a strong baseline.

But developer queries are often much messier than package names.

People search for:

• rrf

• signin

• pg vector

• hnsw

• raw body stripe

Those aren't “bad” queries. They're realistic shorthand.

And they expose an opportunity in the content model itself: many of the exact answers live in reference files such as references/rrf.md, references/raw-body.md, and references/hnsw.md.

So the question is not whether the current search works at all. It clearly does. The better question is this:

How can you improve retrieval without breaking the content contract that already makes Context Hub useful?

The answer in the companion repo is to keep the current model and add a reranking layer on top of it.

How the Companion Relevance Engine Improves Retrieval

The companion repository in this article is context-hub-relevance-engine.

It keeps the same broad ideas that make Context Hub attractive:

• plain Markdown content

• DOC.md and SKILL.md entry points

• build artifacts you can inspect

• local annotations and feedback

• progressive fetch behavior

Then it adds one new build artifact: signals.json.

At build time, the engine extracts extra signals such as:

• headings from the main file

• titles and tokens from reference files

• language and version metadata

• source metadata and freshness

• annotation overlap

• feedback priors

The first pass stays cheap and transparent. The reranker only runs after the baseline has done its work.

That approach matters for two reasons.

First, it's additive. You don't have to redesign the content tree.

Second, it's measurable. You can define concrete failure modes, fix them one by one, and run the same benchmark every time you change the scorer.

How to Run the Companion Repo End to End

Open the repository on GitHub, clone it using GitHub’s normal clone flow, and then run the commands below from the project root.

cd context-hub-relevance-engine
npm install
npm run build
npm test

The repository has no third-party runtime dependencies, so npm install is mostly there to keep the workflow familiar. The main commands are all plain Node scripts.

How to Reproduce a Baseline Miss

Start with the query rrf.

node bin/chub-lab.mjs search rrf --mode baseline --lang python

Expected output:

No results.

Now run the improved mode.

node bin/chub-lab.mjs search rrf --mode improved --lang python

Expected top result:

langchain/retrievers [doc] score=320.24
  Composable retrieval patterns for hybrid search, parent documents, query expansion, and reranking.

That win happens because the improved mode looks beyond the top-level entry description. It also sees the reference file title rrf, the related terms from query expansion, and the broader token overlap in the extracted signals.

How to Reproduce a Workflow-intent Win

Try a sign-in query.

node bin/chub-lab.mjs search signin --mode baseline
node bin/chub-lab.mjs search signin --mode improved

The baseline misses. The improved mode returns playwright-community/login-flows because the reranker treats signin, sign in, login, and authentication as related intent.

How to Test the Memory Loop

Write a local note:

node bin/chub-lab.mjs annotate stripe/webhooks \
  "Remember: Flask request.data must stay raw for Stripe signature verification."

Then fetch the doc:

node bin/chub-lab.mjs get stripe/webhooks --lang python

You will see the main doc content, the list of available reference files, and the appended annotation.

That's the behavior you want from an agent memory loop: learn once, reuse many times.

How to Run the Benchmark

Start from an empty store:

npm run reset-store
node bin/chub-lab.mjs evaluate

The included synthetic stress set reports the following summary with an empty store:

You can also seed the store and rerun the evaluation:

npm run seed-demo
node bin/chub-lab.mjs evaluate

That demonstrates how annotations and feedback can push relevant entries even higher when the query overlaps with the agent’s own history.

How to Launch the Local Comparison UI

npm run serve

Then open http://localhost:8787 in your browser.

The UI lets you compare baseline and improved retrieval, inspect stored annotations and feedback, rebuild the local artifacts, and rerun the benchmark from one place.

How to Read the Benchmark Honestly

The benchmark in this repo is intentionally small.

That is a feature, not a flaw.

The point is not to claim universal search quality. The point is to make a handful of realistic failure modes easy to reproduce:

• acronym queries

• shorthand workflow queries

• reference-file topic queries

• memory-aware reranking

That keeps the evaluation honest.

If a future scoring change breaks rrf, signin, or raw body stripe, you'll know immediately. And if you add a stronger dataset later, you can keep these tests as regression guards.

The benchmark files included in the repo are:

• demo/benchmark.json

• docs/benchmark-empty-store.json

• docs/benchmark-seeded-store.json

• docs/relevance-improvement-plan.md

How to Connect the Companion Repo to the Upstream PR

A good companion repo is broad enough to explore ideas quickly. A good upstream PR is narrow enough to review.

That's why the two shouldn't be identical.

The companion repository is where you can keep the full relevance story together:

• the local comparison UI

• the synthetic benchmark

• the richer reranking signals

• the debug and explain surfaces

• the documentation that walks through tradeoffs end to end

The upstream PR should be smaller and more surgical. In practice, that usually means proposing the most reviewable slices first, such as:

1. reference-file signal extraction

2. explainable score output for debugging

3. a lightweight benchmark fixture format

4. one additive reranking hook behind a flag

That keeps the main repository maintainable while still letting the article and companion repo tell the full engineering story. The upstream thread for this work lives here: andrewyng/context-hub pull requests by natarajsundar.

Conclusion

What makes Context Hub interesting is not just that it stores documentation. It gives you a clear system boundary for improving coding agents.

You can inspect what the agent reads. You can decide when it should retrieve. You can layer public and private sources. You can persist local lessons. And you can improve ranking without tearing the whole model apart.

The companion relevance engine shows how to keep what already works, make one part of the system measurably better, and package the result in a way other developers can run, inspect, and extend. The upstream PR, in turn, shows how to turn a broad idea into smaller pieces that are realistic to review in the main project.

Diagram Attribution

All diagrams used in this article were created by the author specifically for this tutorial and its companion repository.

Sources

• Context Hub repository

• Context Hub README

• Context Hub CLI README

• Context Hub CLI reference

• Context Hub content guide

• Context Hub bring-your-own-docs guide

• Context Hub feedback and annotations guide

• Companion repository: context-hub-relevance-engine

• Upstream pull request search filtered by author

In practice, this means you can run a web app on your laptop and instantly make it accessible to external services, teammates, or clients without configuring routers, DNS, or firewalls.

It's widely used for webhook testing, API development, demos, and remote debugging.

The core idea behind ngrok is simple: it creates an outbound connection from your local machine to a cloud relay service. That relay provides a public endpoint and forwards traffic back to your local port.

This outbound-only design avoids many networking problems and works even behind NAT or strict corporate firewalls.

But as teams scale or requirements change, many developers start looking for alternatives. Some want more control, some want open source tooling, and others want tighter security models or lower cost.

In 2026, the ecosystem around tunneling and secure exposure has matured significantly, and several tools now compete directly with ngrok depending on your use case.

This article explores five strong ngrok alternatives that developers are actively using today. Each one approaches tunneling slightly differently, and understanding those differences is important before choosing a tool for production or development workflows.

LocalXpose

LocalXpose positions itself as a reverse proxy designed specifically for developers who want to expose localhost services quickly while keeping debugging visibility. The platform supports multiple tunnel types, including HTTP, TCP, TLS, UDP, and more, which makes it flexible beyond simple web apps.

One notable aspect of LocalXpose is its emphasis on traffic inspection. Developers can inspect requests and replay payloads, which is extremely useful when working with webhooks or third-party integrations. Instead of simply forwarding traffic, it becomes a debugging layer that helps you understand exactly what external services are sending into your application.

From a workflow perspective, LocalXpose feels closer to a developer productivity tool than just a networking utility. The CLI allows fast tunnel creation, while configuration files make it possible to start multiple tunnels simultaneously, which is helpful when testing microservices or event-driven architectures.

The tradeoff is that it still relies on an external relay infrastructure, so teams with strict compliance requirements may prefer self-hosted solutions. But for everyday development and demos, it offers a polished experience that many developers find comparable or even superior to ngrok.

LocalXpose works particularly well if you value debugging visibility and want a smoother developer experience without managing infrastructure.

LocalTunnel

LocalTunnel is one of the oldest and simplest alternatives in the ecosystem.

Its philosophy is minimalism. You run a single command, and your local server becomes publicly available through a generated URL. There is no heavy setup, no DNS configuration, and almost no learning curve.

Because it's open source, LocalTunnel appeals strongly to developers who prefer transparent tooling. The server component can be self-hosted, which gives teams more control over reliability and privacy if they don't want to depend on public infrastructure.

The simplicity of LocalTunnel is both its strength and its limitation. It focuses primarily on HTTP and HTTPS use cases. Advanced enterprise features, detailed analytics, and complex access controls are not the main goal. Instead, it excels at quick sharing during development, hackathons, or rapid testing cycles.

One important consideration is reliability. Since many people use public LocalTunnel servers, availability can vary depending on community infrastructure. Developers often solve this by deploying their own server instance when stability becomes important.

In 2026, LocalTunnel remains relevant because of its low friction. If your goal is simply to share a local service quickly and you prefer open source tools, it remains a practical and lightweight choice.

Cloudflare Tunnel

Cloudflare Tunnel takes a more infrastructure-oriented approach compared to developer-centric tunneling tools. Instead of just exposing localhost, it integrates directly with Cloudflare’s global network and security platform.

The tunnel is created through the cloudflared daemon, which establishes outbound connections to Cloudflare and routes traffic through their edge network.

This architecture changes how you think about tunnels. Rather than temporary developer links, Cloudflare Tunnel can be used as a production-grade access layer for private services.

You can publish internal applications without opening inbound ports, which significantly reduces the attack surface. The connection is outbound-only, meaning your origin server doesn't accept direct internet traffic.

Another major advantage is ecosystem integration. Since Cloudflare Tunnel sits inside the broader Cloudflare platform, you can combine it with access policies, DNS management, and performance features. This makes it attractive for teams already using Cloudflare for domains or security.

The tradeoff is complexity. Compared to LocalXpose or LocalTunnel, setup involves authentication, configuration, and a deeper understanding of networking concepts. But once configured, it scales well and fits long-term deployments rather than temporary development sessions.

Cloudflare Tunnel is ideal when your tunneling needs start blending into infrastructure and security strategy instead of just development convenience.

Tailscale

Tailscale isn't a traditional tunnel in the same sense as ngrok. It's primarily a mesh VPN built on WireGuard principles, designed to securely connect devices into a private network called a tailnet.

But features like Tailscale Funnel allow services inside that private network to be exposed safely to the public internet, effectively making it a strong alternative for certain tunneling scenarios.

The key difference is security architecture. Instead of routing everything through a central relay by default, Tailscale builds encrypted peer-to-peer connections whenever possible. This means your devices become part of a secure overlay network, and exposure to the internet becomes a deliberate extension rather than the default behaviour.

Tailscale Funnel allows developers to expose local services externally while maintaining strong isolation from the rest of the network. Funnel ingress nodes are specifically designed so they don't gain packet-level access to your private tailnet, which is an important security design detail.

From a practical standpoint, Tailscale is excellent for teams that already need secure remote access. Instead of adding a separate tunneling tool, you extend an existing secure network to share services when necessary.

The downside is conceptual overhead. Developers expecting a simple “run one command and get a URL” experience may find the networking model more complex. But for engineering teams thinking about long-term secure connectivity, Tailscale offers a modern alternative that aligns well with zero-trust principles.

Boring Proxy (Open Source Self-Hosted Option)

Boring Proxy represents a different philosophy entirely. It's designed for self-hosters who want full control over their tunneling infrastructure. Instead of relying on a third-party cloud relay, you deploy your own server and manage tunnels through a lightweight web interface.

The project describes itself as a no-frills HTTPS and SSH tunneling solution focused on automation. Features like automatic HTTPS and a fast web UI make it approachable even for developers who don't want to manually manage certificates or reverse proxy configurations.

One of the biggest advantages is ownership. Because everything runs on your infrastructure, you control uptime, data flow, and security policies. This makes Boring Proxy especially attractive for developers running homelabs, internal tools, or privacy-focused projects.

Community discussions often compare it to a simplified mix of Caddy and ngrok, emphasising its usability for self-hosted environments.

The tradeoff is that you must manage a server. Unlike hosted solutions, you're responsible for maintenance, updates, and reliability. For some teams, this is a burden, but for others it's precisely the point.

In 2026, Boring Proxy stands out as one of the most practical open source options for developers who want ngrok-style convenience without vendor dependence.

Choosing the Right Alternative

Selecting an ngrok alternative is less about features and more about intent.

If your goal is rapid development sharing, LocalTunnel or LocalXpose provides minimal friction. If you are thinking about secure production exposure, Cloudflare Tunnel is a strong infrastructure-level choice.

If you want network-centric security and remote access, Tailscale changes the model entirely. And if control and ownership matter most, Boring Proxy gives you a self-hosted path.

The tunneling ecosystem has matured significantly over recent years. Instead of a single dominant tool, developers now choose based on workflow philosophy. Some prioritise speed, some prioritise security, and others prioritise ownership.

The best approach is to treat tunneling as part of your architecture rather than a temporary utility. Once you do that, the right alternative becomes obvious based on how your team builds, deploys, and collaborates.

Final Thoughts

ngrok remains influential, but it's no longer the only default choice. The tools covered here show how tunneling has evolved from simple developer shortcuts into a broader category that overlaps with networking, security, and infrastructure management.

LocalXpose and LocalTunnel keep things lightweight and developer-friendly. Cloudflare Tunnel introduces enterprise-grade edge networking. Tailscale blends secure mesh networking with public exposure when needed. Boring Proxy empowers developers who want to own the entire stack.

The right decision depends on where you sit on the spectrum between convenience and control. In 2026, you no longer need to compromise. There is an option tailored to almost every development workflow.

Hope you enjoyed this article. Learn more about me by visiting my website.

Personalization is one of the most requested features in AI-powered applications. Users expect an agent to remember their preferences, adapt to their style, and improve over time.

In practice, personalization is unfortunately also one of the fastest ways to break an otherwise working AI agent.

Many agents start with a simple idea: keep adding more conversation history to the prompt. This approach works for demos, but it quickly fails in real applications. Context windows grow too large. Irrelevant information leaks into decisions. Costs increase. Debugging becomes nearly impossible.

If you want a personalized agent that survives production, you need more than a large language model. You need a way to connect the agent to tools, manage multi-step workflows, and store user preferences safely over time – without turning your system into a tangled mess of prompts and callbacks.

In this tutorial, you’ll learn how to design a personalized AI agent using three core building blocks:

• Agent Development Kit (ADK) to orchestrate agent reasoning and execution

• Model Context Protocol (MCP) to connect tools with clear boundaries

• Long-term memory to store preferences without polluting context

Rather than focusing on setup commands or vendor-specific walkthroughs, we'll focus on the architectural patterns that make personalized agents reliable, debuggable, and maintainable.

Figure 1 — Personalization influences agent responses

Table of Contents

• Prerequisites

• What “Personalized” Means in a Real AI Agent

• How the Agent Architecture Fits Together

• How to Design the Agent Core with ADK

• How to Connect Tools Safely with MCP

• How to Add Long-Term Memory Without Polluting Context

  • Privacy, Consent, and Lifecycle Controls (Production Checklist)

• How the End-to-End Agent Flow Works

• Common Pitfalls You’ll Hit (and How to Avoid Them)

• What You Learned and Where to Go Next

Prerequisites

To follow along with this tutorial, you should have:

• Basic familiarity with Python

• A general understanding of how large language models work

• Optional: a Google Cloud account if you want to run an end-to-end demo. Otherwise, you can follow the architecture and code patterns locally with stubs. We’ll avoid deep infrastructure setup and focus on design patterns rather than deployment mechanics.

You don’t need prior experience with ADK or MCP. I’ll introduce each concept as it appears.

What “Personalized” Means in a Real AI Agent

Figure 2 — Keep preferences out of the prompt: agent ↔ tools across a protocol boundary

Before writing any code, it’s important to define what personalization means in an AI agent.

Personalization is not the same as “remembering everything.” In practice, agent state usually falls into three categories:

1. Short-term context: Information needed to complete the current task. This belongs in the prompt.

2. Session state: Temporary decisions or selections made during a workflow. This should be structured and scoped to a session.

3. Long-term memory: Durable user preferences or facts that should persist across sessions.

Figure 3 — Three kinds of agent state: context (now), session (today), memory (always)

Most problems happen when these categories are mixed together.

If you store long-term preferences directly in the prompt, the agent’s behavior becomes unpredictable. If you store everything permanently, memory grows without bounds. If you don’t scope memory at all, unrelated sessions start influencing each other.

A well-designed, personalized agent treats memory as a first-class system component, not as extra text added to a prompt.

In the next section, we'll look at how to structure the agent so these concerns stay separated.

By the end of this tutorial, you’ll understand how to design a personalized AI agent that uses long-term memory safely, connects to tools through clear boundaries, and remains debuggable as it grows.

How the Agent Architecture Fits Together

Figure 4 — Reference architecture: agent core + tools + memory service + orchestration runtime

The above diagram shows a high-level, personalized AI agent architecture. In it, an agent core handles reasoning and planning while interacting with a tool interface layer, a long-term memory service, and an orchestration runtime.

Let’s now understand the moving parts of a personalized agent and how they interact.

At a high level, the system has four responsibilities:

1. Reasoning – deciding what to do next

2. Execution – calling tools and services

3. Memory – storing and retrieving long-term preferences

4. Boundaries – controlling what the agent is allowed to do

A common mistake you’ll see is to blur these responsibilities together. For example, letting the model decide when to write memory, or allowing tools to execute actions without clear constraints.

Instead, you'll design the system so each responsibility has a clear owner. The core components look like this:

• Agent core: Handles reasoning and planning

• Tools: Perform external actions (read or write)

• MCP layer: Defines how tools are exposed and invoked

• Memory services: Store long-term user data safely

ADK sits at the center, orchestrating how requests flow between these components. The model never directly talks to databases or services. It reasons about actions, and ADK coordinates execution.

This separation makes the system easier to reason about, debug, and extend.

How to Design the Agent Core with ADK

Before we dive in, a quick note on what ADK is.

Agent Development Kit (ADK) is an agent orchestration framework – the glue code between a large language model and your application. Instead of treating the model as a black box that directly “does things”, ADK helps you structure the agent as a system:

• The model focuses on reasoning (turning user intent, context, and memory into a structured plan)

• Your runtime stays in control of execution (deciding which tools can run, how they run, and what gets logged or persisted)

In other words, ADK is what lets you take tool calling and multi-step workflows out of a giant prompt and turn them into a maintainable and testable architecture. In this tutorial, we’ll use ADK to refer to that orchestration layer. The same patterns apply if you use a different agent framework.

Note: The following code snippets are simplified reference examples intended to illustrate architectural patterns. They’re not production-ready drop-ins.

Once you understand the architecture, you can start designing the agent core. The agent core is responsible for reasoning, not execution.

A helpful mental model is to think of the agent as a planner, not a doer. Its role is to interpret the user’s goal, consider available context and memory, and produce a structured plan that can later be executed in a controlled way.

To make this concrete, the following example shows how an agent can translate user input and memory into an explicit plan. In practice, ADK orchestrates this using a large language model, but the important idea is that the output is structured intent, not side effects.

# Reference example for illustration.

from dataclasses import dataclass
from typing import List, Dict, Any

@dataclass
class Step:
    tool: str
    args: Dict[str, Any]

@dataclass
class Plan:
    goal: str
    steps: List[Step]

def build_plan(user_text: str, memory: Dict[str, Any]) -> Plan:
    # In practice, the LLM produces this structure via ADK orchestration.
    goal = f"Help user: {user_text}"
    steps = []
    if memory.get("prefers_short_answers"):
        steps.append(Step(tool="set_style", args={"verbosity": "low"}))
    steps.append(Step(tool="search_docs", args={"query": user_text}))
    steps.append(Step(tool="summarize", args={"max_bullets": 5}))
    return Plan(goal=goal, steps=steps)

This example illustrates an important constraint: the agent produces a plan, but it doesn’t execute anything directly.

The agent decides what should happen and in what order, while ADK controls when and how each step runs. This separation lets you inspect, test, and reason about decisions before they result in real-world actions.

When personalization is involved, this distinction becomes critical. Preferences may influence planning, but execution should remain tightly controlled by the runtime.

Again, we can consider the agent to be a planner, not a doer.

It should not:

• Perform side effects directly

• Write to databases

• Call external APIs without supervision

In ADK, this separation is natural. The agent produces intents and tool calls, while the runtime controls how and when those calls are executed.

This design has two major benefits:

1. Safety – you can restrict which tools the agent can access

2. Debuggability – you can inspect decisions before execution

When personalization is involved, this becomes even more important. Preferences influence reasoning, but execution should remain tightly controlled.

How to Connect Tools Safely with MCP

Figure 5 — Tool calls with guardrails: request → validate → execute → respond

Tools are how agents interact with the real world. They fetch data, generate artifacts, and sometimes perform actions with side effects.

Without clear boundaries, tool usage quickly becomes a source of fragility. Hardcoded API calls leak into prompts, tools evolve independently, and agents gain more authority than intended.

To avoid these problems, tools should be explicitly registered and invoked through a narrow interface. The following example shows a simple tool registry pattern that mirrors how MCP exposes tools to an agent without tightly coupling it to implementations.

# Reference example (pseudocode for illustration)

from typing import Callable, Dict, Any

ToolFn = Callable[[Dict[str, Any]], Dict[str, Any]]

TOOLS: Dict[str, ToolFn] = {}

def register_tool(name: str):
    def decorator(fn: ToolFn):
        TOOLS[name] = fn
        return fn
    return decorator

@register_tool("search_docs")
def search_docs(args: Dict[str, Any]) -> Dict[str, Any]:
    query = args["query"]
    # Replace with your MCP client call (or local tool implementation).
    return {"results": [f"doc://example?q={query}"]}

def invoke_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
    if name not in TOOLS:
        raise ValueError(f"Tool not allowed: {name}")
    return TOOLS[name](args)

The Model Context Protocol (MCP) provides a clean way to formalize this pattern. You can think of MCP the same way operating systems treat system calls.

An application does not directly manipulate hardware. Instead, it requests operations through well-defined system calls. The kernel decides whether the operation is allowed and how it executes.

In the same way, the agent knows what capabilities exist, MCP defines how those capabilities are invoked, and the runtime controls when and whether they execute.

This separation prevents several common problems, including hardcoded API details in prompts, unexpected breakage when tools change, and agents performing unrestricted side effects.

When designing tools, it helps to classify them by risk: read tools for safe queries, generate tools for planning or synthesis, and commit tools for irreversible actions. In a personalized agent, commit tools should be rare and tightly guarded.

Figure 6 — Observability around tool calls: logs, traces, timing, decision points

How to Add Long-Term Memory Without Polluting Context

Figure 7 — Memory admission pipeline: extract → filter/validate → persist asynchronously

Memory is where personalization either succeeds or fails.

You can start by storing everything the user says and feed it back into the prompt. This works briefly, then collapses under its own weight as context grows, costs rise, and behavior becomes unpredictable.

A better approach is to treat memory as structured, curated data so you can control what the agent remembers and why with clear admission rules. Before persisting anything, the system should explicitly decide whether the information is worth remembering. The following function demonstrates a simple memory admission policy.

# Simplified Reference Only
from typing import Optional, Dict, Any

def memory_candidate(user_text: str) -> Optional[Dict[str, Any]]:
    text = user_text.lower()

    # Durable
    if "for this session" in text or "ignore after" in text:
        return None

    # Reusable
    if "my preferred language is" in text:
        return {"type": "preference", "key": "language", "value": user_text.split()[-1]}

    # Safe (basic example; add PII checks for your use case)
    if "password" in text or "ssn" in text:
        return None

    return None  # default: don’t store

This policy encodes three questions every memory candidate must answer:

• Is it durable? Will it still matter in the future?

• Is it reusable? Will it influence future decisions meaningfully?

• Is it safe to persist? Does it avoid sensitive or session-specific data?

Only information that passes all three checks should become long-term memory. In practice, this usually includes stable preferences and long-lived constraints, not temporary instructions or intermediate reasoning.

Privacy, Consent, and Lifecycle Controls (Production Checklist)

Even if your admission rules are solid, long-term memory introduces governance requirements:

• User control: allow users to view, export, and delete stored preferences at any time.

• Sensitive data handling: never store secrets/PII. Run PII detection on every memory candidate (and consider redaction).

• Retention + consent: use explicit consent for persistent memory and apply retention windows (TTL) so memory expires unless it’s still useful.

• Security + auditability: encrypt at rest, restrict access by service identity, and keep an audit log of memory writes/updates.

Memory writes should also be asynchronous. The agent should never block while persisting memory, which keeps interactions responsive and avoids coupling reasoning to storage latency.

How the End-to-End Agent Flow Works

Figure 8 — End-to-end request lifecycle: user input → plan → tools → memory updates

At this point, you can trace exactly how memory and tools interact during a single request. With the individual components in place, it’s helpful to see how they work together during a single request. The following example walks through the full lifecycle of a personalized interaction, from user input to response.

# Reference example (pseudocode for illustration)

def handle_request(user_id: str, user_text: str) -> str:
    memory = memory_store.get(user_id)  # e.g., {"prefers_short_answers": True}
    plan = build_plan(user_text, memory)

    tool_outputs = []
    for step in plan.steps:
        out = invoke_tool(step.tool, step.args)
        tool_outputs.append({step.tool: out})

    response = render_response(goal=plan.goal, tool_outputs=tool_outputs, memory=memory)

    cand = memory_candidate(user_text)
    if cand:
        # Never block the user on storage.
        memory_store.write_async(user_id, cand)
    return response

At a high level, the flow looks like this:

1. The user sends a message.

2. Relevant long-term memory is retrieved.

3. The agent reasons about the request and produces a plan.

4. ADK invokes tools through MCP as needed.

5. Results flow back to the agent.

6. The agent decides whether new information should be persisted.

7. Memory is written asynchronously.

8. The final response is returned to the user.

Notice what does not happen: the model does not directly write memory, tools do not execute without coordination, and context does not grow without bounds. This structure keeps personalization controlled and predictable.

Common Pitfalls You’ll Hit (and How to Avoid Them)

Even with a solid architecture, there are a few failure modes that show up repeatedly in real systems. Many of them stem from allowing agents to perform irreversible actions without explicit checks.

The following example shows a simple guardrail for commit-style tools that require approval before execution.

# Reference example (pseudocode for illustration)

def invoke_commit_tool(name: str, args: Dict[str, Any], approved: bool) -> Dict[str, Any]:
    if not approved:
        # Require explicit confirmation or policy approval before side effects.
        return {"status": "blocked", "reason": "commit tools require approval"}

    # For example: create_ticket, send_email, submit_order, update_record
    return invoke_tool(name, args)

This pattern forces a clear decision point before side effects occur. It also creates an audit trail that explains why an action was allowed or blocked.

Other common pitfalls include over-personalization, leaky memory that persists session-specific data, uncontrolled tool growth, and debugging blind spots caused by unclear boundaries. If you see these symptoms, it usually means responsibilities are not clearly separated.

What You Learned and Where to Go Next

Personalized AI agents are powerful, but they require discipline. The key insight is that personalization is a systems problem, not a prompt problem.

By separating reasoning from execution, structuring memory carefully, and using protocols like MCP to enforce boundaries, you can build agents that scale beyond demos and remain maintainable in production.

As you extend this system, resist the urge to add “just one more prompt tweak.” Instead, ask whether the change belongs in memory, tools, or orchestration.

That mindset will save you time as your agent grows in complexity.

If you’d like to continue the conversation, you can find me on LinkedIn.

*All diagrams in this article were created by the author for educational purposes.

After quite a journey of trial and error, I found WebCurate, a platform that felt like the instruction manual I’d been missing.

In this article, I’ll take you through how WebCurate helped me simplify my journey with Kreed and share tips on discovering the best tools for your projects.

What We’ll Cover

• What is WebCurate?: An overview of WebCurate’s platform

• How WebCurate Works: A look at WebCurate's curated categories to streamline your workflow.

• Finding the Right Tools: Tips for searching, filtering, and using WebCurate’s curated recommendations.

• Making the Most of WebCurate: Advice on leveraging the platform for your specific needs, with an example of finding a relevant tool.

• Essential Tools Discovered on WebCurate: A look at the essential tools WebCurate helped me discover for Kreed’s development and how they might help you.

What is WebCurate?

WebCurate is a free platform designed to help developers, startups, and tech enthusiasts find high-value tools without the overwhelm.

Unlike other resources that flood you with endless options, WebCurate handpicks practical, relevant tools and resources tailored for productivity and development.

What makes WebCurate unique is its comprehensive scope. It offers a curated range of design tools and inspiration, developer tools, API integrations, debugging utilities, productivity aids, and even insights into industry trends.

Each resource on WebCurate is chosen for its ability to genuinely enhance workflow and project outcomes, so you spend less time searching and more time building.

How WebCurate Works

WebCurate provides resources across essential categories, like design assets, developer tools, and productivity guides. Think of it like a “greatest hits” album but for tools.

The platform features resources that span several essential areas:

• Design Assets: From UI kits to icons and templates, WebCurate provides carefully selected design resources that can help developers and designers keep their projects on track without feeling lost in a sea of options.

• Developer Tools: This includes everything from code libraries to APIs and frameworks that can speed up development workflows. Tools like these are sorted into categories to ensure you find the best fit for your tech stack.

• Industry Guides: WebCurate also offers practical guides tools, insights, and case studies to help developers stay ahead of industry trends and optimize their strategies.

Finding the Right Tools: Tips for Navigation

Efficient Search & Filtering

WebCurate’s search and filtering functions make it simple to find exactly what you need, fast. Whether you’re after an API for a new feature or a project management tool, these features help narrow your options to the most relevant tools quickly and effectively.

Curated Recommendations

What sets WebCurate apart is its thoughtful curation. Instead of suggesting random, popular tools, it presents resources that address real developer needs, based on industry trends and emerging technologies. This means you’re seeing tools that make an impact—tailored to current, practical needs.

Example: Task Management Tools

For instance, searching for “task management” within the "Productivity" filter quickly revealed tools aligned with my development approach.

By using filters for categories like "Development" or "Productivity," WebCurate connects you with tools tailored to your tech stack.

How You Can Make the Most of WebCurate

I’ve told you a bit about how WebCurate helped me find essential tools and resources while building Kreed. But let’s be real, the value of a tool lies in how you use it.

So, if you’re thinking about trying WebCurate out for your next project or even just to optimize your workflow, here’s how you can make the most of it:

1. Start with Your Needs: The first step is identifying what you actually need. Are you a developer trying to optimize your front-end stack? A product manager looking for tools to boost team productivity? Or maybe you’re just exploring new ways to streamline your projects? WebCurate’s search and filtering system allows you to narrow down tools based on what you're looking for, so spend some time defining your needs.

2. Use the Developer Section to Your Advantage: For anyone working in tech, the Developer section is a must. It’s tailored to provide the most relevant resources for developers, from libraries and frameworks to APIs and deployment tools. For me, it saved hours of research and trial and error. Don’t just browse the section—dig into it, explore the recommendations, and filter by categories or specific tools you’re interested in.

3. Filter and Refine Your Search: WebCurate lets you filter by categories like design, front-end development, back-end tools, and even productivity. When you search, take the time to refine your results so you’re only seeing what’s most relevant. For instance, if you’re building a React app, filter for tools that integrate well with React—WebCurate will show you options that are perfect for your tech stack. And since every tool is vetted by the community, you know you’re not wasting time with gimmicks.

4. Keep an Open Mind and Explore: While it’s helpful to focus on exactly what you’re looking for, WebCurate also encourages a bit of exploration outside your comfort zone. You might stumble upon a tool or resource you hadn’t thought of but that could genuinely elevate your project. Just don’t get lost in endless scrolling—keep your objective in mind. It’s easy to get sidetracked exploring, but remember, you’re here to find tools that push your project forward, not to doom scroll your way to zero productivity.

5. Experiment with New Tools and Stay Updated: Building a product is fundamentally about iteration, and this principle extends to the tools you choose to support it. WebCurate is a dynamic resource that updates daily with fresh recommendations, making it a valuable tool for discovering new options. Even if you don't need a new tool right now, it's worth revisiting regularly for innovative ideas that could prove useful in the future.

Essential Tools I Discovered on WebCurate

Here’s a rundown of a few tools that I found interesting on WebCurate—some are longtime favourites, while others were discoveries that have quickly become essentials.

Tools I Already Use (and Still Love)

• Supabase: An open-source Firebase alternative that simplifies backend development with real-time updates and intuitive database management.

• GSAP: A powerful animation library for creating smooth, high-performance animations (I even wrote an article about how I use it!).

• JsonViewer: A practical tool for viewing and formatting JSON data, making debugging and visualization easier.

• CanIUse: An essential resource for checking browser compatibility across HTML5, CSS3, SVG, and more—perfect for ensuring cross-platform support.

New Tools I Use Often or Plan on Using Soon

• Pesticide for Chrome: A Chrome extension that outlines page elements, helping spot layout issues and verify alignment quickly.

• WindUI: A component library styled with Tailwind CSS, that speeds up development without compromising design quality.

• Mobbin: A curated collection of mobile design patterns, offering inspiration to refine and elevate mobile UI elements.

• Mightly Meld: A collaborative design tool for React that makes feedback gathering and design iteration faster and more streamlined.

• Rowy: A no-code platform connecting directly to databases, allowing for rapid development and deployment of data-driven applications without extensive code.

Wrapping It Up

At the end of the day, building a startup is a mix of hustle, luck, and learning on the fly. And this article just represents a nerd like me geeking out over tools that made a difference (and resisting the urge to gatekeep 😂).

Finding WebCurate didn’t magically solve all my challenges, but it did cut down on the noise and brought useful resources to my fingertips—a massive win when every minute counts.

If you’re on your startup journey, know this is only part of the ride. Maybe one day I’ll share the full highs and lows of being a founder—assuming I get a break from being Batman 🦇.

Like my articles?

Feel free to buy me a coffee here, to keep my brain chugging and provide more articles like this.

Want to connect?

• Twitter / X: @jajadavid8

• LinkedIn: David Jaja

• Email: Jajadavidjid@gmail.com

FGA allows you to set up detailed access controls that specify who can do what and under which conditions.

In this tutorial, you will learn how to implement fine-grained authorization in Java and Spring Boot using Permit.io.

Here is the source code (remember to give it a star ⭐).

I hope you enjoyed my previous blog about building a custom video conferencing app with Stream and Next.js. These blogs reflect my journey in creating DevTools Academy, a platform designed to help developers discover amazing developer tools.

This tutorial is another effort to introduce you to a super helpful developer tool that I recently explored.

Table of Contents:

• What is Permit?

• Prerequisites

• What is Fine-Grained Authorization?

  • Role-Based Access Control (RBAC)

  • Attribute-Based Access Control (ABAC)

  • Relationship-Based Access Control (ReBAC)

• How to Implement Fine-Grained Authorization

  • Implementing Role-Based Access Control

  • Implementing Attribute-Based Access Control

  • Implementing Relationship-Based Access Control

• How to Implement FGA in Java and SpringBoot

  • Step 1: Setting Up the E-commerce Application

  • Step 2: Get your Environment API Key

  • Step 3: Deploy Policy Decision Point (PDP)

  • Step 4: Running the App

• Next Steps

  • Before We End...

What is Permit?

Permit.io is a full stack, plug-and-play application-level authorization solution that allows you to implement a secure, flexible, authorization layer within minutes, so you can focus on what matters most.

Prerequisites

To fully understand the tutorial, you need to have a basic understanding of Java and Spring Boot. You’ll also need the following:

• Permit.io: A developer tool that simplifies the implementation of FGA.

• Spring Boot Starter Web: Provides essential components for building web applications, including RESTful APIs.

• Gradle: A build tool for managing dependencies.

• JDK 11 or later: The Java Development Kit version required to compile and run your Spring Boot app.

• Postman or cURL: Tools for testing your API endpoints.

What is Fine-Grained Authorization?

Fine-grained authorization offers access control to resources by determining who can access them, to what extent, and under specified conditions.

Contrary to coarse-grained authorization (that handles access based on categories like user roles such as "admin" or "user"), fine-grained authorization gives you the flexibility to define access at a granular level, for specific resources or actions and even attributes.

In Fine Grained Authorization there exist 3 types of policy models for managing authorization; Role Based Access Control (RBAC), Attribute Based Access Control (ABAC), and Relationship-Based Access Control (ReBAC).

Let's take a look, at each of these approaches and see how you can implement them in your application.

Role-Based Access Control (RBAC)

RBAC is a security approach that controls resource access based on the roles of users within an organization. This model streamlines permissions by organizing users into roles and managing access control according to these defined roles.

Key Concepts in RBAC:

Users: People who use the system such as employees or customers.

Roles: A set of permissions or access privileges assigned to a group of users based on their responsibilities or tasks such as admin, manager, or customer.

Permissions: The rights granted to users for interacting with resources, such as read, write, or delete.

Attribute-Based Access Control (ABAC)

ABAC is a versatile and adaptive access control model that decides who can or cannot access resources based on attributes, like user details. The ABAC model allows you to define fine-grained authorization based on user attributes.

Key Concepts in ABAC:

Attributes: Characteristics or properties used to make access control decisions. Attributes are typically categorized into:

• User Attributes: Information about the user (for example, role, department, job title, age, and so on).

• Resource Attributes: Characteristics of the resource (for example, file type, data classification level, creation date, owner).

• Action Attributes: The action the user is trying to perform (for example, read, write, delete, approve).

• Environmental Attributes: Contextual information about the access request (for example, time of day, location, device type, IP address).

Relationship-Based Access Control (ReBAC)

ReBAC is an access control system that grants permissions to access resources based on the relationship between entities within a system. The approach emphasizes defining and managing access control by mapping out how users relate to resources and other entities such as organizations or groups.

Key Concepts of ReBAC:

Entities: Users, resources (such as files and documents), and other entities, such as groups or organizational units.

Relationships: The connections that specify the relationship between two entities. A user might be the "owner" of a document or a "member" of a team, for instance.

Policies: Rules that use relationships to determine access rights. A user can access a resource or execute an action on it if they have a particular relationship with it.

How to Implement Fine-Grained Authorization

Now that you have a basic understanding of RBAC, ABAC, and ReBAC, let’s see how we can implement these models in an e-commerce app.

Implementing Role-Based Access Control

Step 1: Navigate to Permit.io, and then create an account and your workspace.

By default, you should see a project that includes two environments: Development and Production.

Step 2: Create a resource named Products. To create the resource, open the Policy tab on the left sidebar and then open the Resources tab at the top. After that, click the Create a Resource button and then create a resource called Products with actions read, create, update, and delete.

Step 3: Create another resource called Reviews with actions read, create, update, and delete.

Step 4: Open the Policy Editor tab. You’ll see that 3 roles named admin, editor, and viewer were created.

• Role admin has permission to create, delete, read, or update a product or a review.

• Role editor has permission to create, read, or update a product or a review but not delete any.

• Role viewer has permission to create and read a product or a review but not delete or update any.

Implementing Attribute-Based Access Control

Step 1: Open the Resources tab, then click the Add Attributes button.

• Add an attribute called vendor

• Add an attribute called the customer

Step 2: Open the ABAC Rules tab, then create a new ABAC Resource Set called Own Products that depends on the Products resource. After that, add a condition that gives permissions only to the user who created a product based on the vendor attribute.

Step 3: Create another ABAC Resource Set called Own Reviews that depends on the Reviews resource.

Implementing Relationship-Based Access Control

Step 1: Open the Resources tab and edit the Products resource. Add role vendor in the ReBAC options section. Then set products as parent of reviews in the relations section.

Step 2: Edit the Reviews resource by adding role customer in the ReBAC options section, as shown below:

Step 3: Go to Policy Editor tab and add:

• role vendor permission to update and delete own products.

• role customer permission to update and delete their own reviews on products.

How to Implement FGA in Java and SpringBoot

Now that we have defined RBAC, ABAC, and ReBAC policies in the Permit.io web interface, let’s learn how to enforce them in an E-Commerce Management System application using the Permit.io API.

There’s a lot of code coming up, so make sure you read through the extensive comments I’ve left throughout each code block. These will help you understand more fully what’s going on in this code.

Step 1: Setting Up the E-commerce Application

To set up the e-commerce application and git clone the source code.

git clone https://github.com/tyaga001/java-spring-fine-grained-auth.git

Installing Permit package SDK

To install the Permit package SDK, you add the SDK under the dependencies block in the build.graddle file.

## Dependencies

To set up the necessary dependencies for your Spring Boot project, include the following in your `build.gradle` file:

```groovy
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

    // Add this line to install the Permit.io Java SDK in your project
    implementation 'io.permit:permit-sdk-java:2.0.0'
}

Initializing the Permit SDK

You can initialize the Permit SDK Client using the code below:

package com.boostmytool.store.config;

import io.permit.sdk.Permit;
import io.permit.sdk.PermitConfig;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration  // Marks this class as a configuration class for Spring IoC
public class PermitClientConfig {

    @Value("${permit.api-key}")  // Inject Permit API key from application properties
    private String apiKey;

    @Value("${permit.pdp-url}")  // Inject Permit PDP (Policy Decision Point) URL from application properties
    private String pdpUrl;

    /**
     * Creates a Permit client bean with custom configuration
     * @return Permit client instance
     */
    @Bean
    public Permit permit() {
        return new Permit(
                new PermitConfig.Builder(apiKey)  // Initialize PermitConfig with API key
                        .withPdpAddress(pdpUrl)   // Set the PDP address
                        .withDebugMode(true)      // Enable debug mode for detailed logging
                        .build()                  // Build the PermitConfig object
        );
    }
}

Syncing Users with SDK

To start enforcing permissions, you should first sync a user to Permit, and then assign them a role.

In the code below, the UserService class provides methods for user login, signup, role assignment, and authorization, with exception handling for possible errors when interacting with the Permit API.

package com.boostmytool.store.service;

import com.boostmytool.store.exception.ForbiddenAccessException;
import com.boostmytool.store.exception.UnauthorizedException;
import io.permit.sdk.Permit;
import io.permit.sdk.api.PermitApiError;
import io.permit.sdk.api.PermitContextError;
import io.permit.sdk.enforcement.Resource;
import io.permit.sdk.enforcement.User;
import org.springframework.stereotype.Service;

import java.io.IOException;

@Service  // Marks this class as a Spring service, making it a candidate for component scanning
public class UserService {
    private final Permit permit;

    // Constructor injection for the Permit SDK
    public UserService(Permit permit) {
        this.permit = permit;
    }

    /**
     * Simulates user login by creating and returning a Permit User object.
     * 
     * @param key User's unique key
     * @return User object
     */
    public Object login(String key) {
        return new User.Builder(key).build();
    }

    /**
     * Handles user signup by creating and syncing a new Permit User.
     * 
     * @param key User's unique key
     * @return Created and synced User object
     */
    public User signup(String key) {
        var user = new User.Builder(key).build();
        try {
            permit.api.users.sync(user);  // Syncs the new user with the Permit service
        } catch (PermitContextError | PermitApiError | IOException e) {
            throw new RuntimeException("Failed to create user", e);  // Handles exceptions during user creation
        }
        return user;
    }

    /**
     * Assigns a role to the user within the "default" environment.
     * 
     * @param user User object to assign the role to
     * @param role Role to be assigned
     */
    public void assignRole(User user, String role) {
        try {
            permit.api.users.assignRole(user.getKey(), role, "default");  // Assigns role in the "default" environment
        } catch (PermitApiError | PermitContextError | IOException e) {
            throw new RuntimeException("Failed to assign role to user", e);  // Handles exceptions during role assignment
        }
    }

    /**
     * Checks if the user is authorized to perform a specific action on a resource.
     * 
     * @param user User object requesting authorization
     * @param action Action to be authorized
     * @param resource Resource on which the action will be performed
     * @throws UnauthorizedException if user is not logged in
     * @throws ForbiddenAccessException if user is denied access
     */
    public void authorize(User user, String action, Resource resource) {
        if (user == null) {
            throw new UnauthorizedException("Not logged in");  // Throws exception if user is not logged in
        }
        try {
            var permitted = permit.check(user, action, resource);  // Performs authorization check
            if (!permitted) {
                throw new ForbiddenAccessException("Access denied");  // Throws exception if access is denied
            }
        } catch (PermitApiError | IOException e) {
            throw new RuntimeException("Failed to authorize user", e);  // Handles exceptions during authorization
        }
    }
}

Then in the code below, the UserController class exposes REST API endpoints for user signup and role assignment. It interacts with the UserService class to handle user-related business logic and provides appropriate HTTP responses.

package com.boostmytool.store.controllers;

import com.boostmytool.store.exception.UnauthorizedException;
import com.boostmytool.store.service.UserService;
import io.permit.sdk.enforcement.User;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController  // Indicates that this class handles HTTP requests and returns JSON responses
@RequestMapping("/api/users")  // Base URL path for all user-related operations
public class UserController {
    private final UserService userService;

    // Constructor injection of UserService, containing business logic for user operations
    public UserController(UserService userService) {
        this.userService = userService;
    }

    /**
     * Handles user signup requests.
     * Endpoint: POST /api/users/signup
     * 
     * @param key Unique key for the new user
     * @return Created User object
     */
    @PostMapping("/signup")
    public User signup(@RequestBody String key) {
        return userService.signup(key);  // Calls the signup method in UserService to create a new user
    }

    /**
     * Handles assigning a role to the logged-in user.
     * Endpoint: POST /api/users/assign-role
     * 
     * @param request HTTP request, used to retrieve the current user
     * @param role Role to be assigned to the current user
     */
    @PostMapping("/assign-role")
    public void assignRole(HttpServletRequest request, @RequestBody String role) {
        // Retrieves the current user from the request attributes
        User currentUser = (User) request.getAttribute("user");

        // Throws an exception if the user is not logged in
        if (currentUser == null) {
            throw new UnauthorizedException("Not logged in");
        }

        // Assigns the specified role to the current user
        userService.assignRole(currentUser, role);
    }
}

Creating RBAC, ABAC, and ReBAC Policy Enforcement Point

In the code below, the ProductService class manages CRUD operations for products and reviews, handling permissions and roles via the Permit API.

Each operation includes user authorization checks, with appropriate exception handling for Permit API errors and resource not found scenarios.

package com.boostmytool.store.service;

import com.boostmytool.store.exception.ResourceNotFoundException;
import com.boostmytool.store.model.Product;
import com.boostmytool.store.model.Review;
import io.permit.sdk.Permit;
import io.permit.sdk.api.PermitApiError;
import io.permit.sdk.api.PermitContextError;
import io.permit.sdk.enforcement.Resource;
import io.permit.sdk.enforcement.User;
import io.permit.sdk.openapi.models.RelationshipTupleCreate;
import io.permit.sdk.openapi.models.ResourceInstanceCreate;
import io.permit.sdk.openapi.models.RoleAssignmentCreate;
import org.springframework.stereotype.Service;

import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.concurrent.atomic.AtomicInteger;

@Service  // Marks this class as a Spring service
public class ProductService {

    private final List<Product> products = new ArrayList<>();  // In-memory list to store products
    private final AtomicInteger productIdCounter = new AtomicInteger();  // Counter to generate unique product IDs
    private final AtomicInteger reviewIdCounter = new AtomicInteger();   // Counter to generate unique review IDs

    // Builders for Permit resource instances (product and review)
    private final Resource.Builder productResourceBuilder = new Resource.Builder("product");
    private final Resource.Builder reviewResourceBuilder = new Resource.Builder("review");

    private final UserService userService;  // Service for handling user-related operations
    private final Permit permit;  // Permit SDK instance for handling authorization and resource management

    // Constructor for injecting dependencies
    public ProductService(UserService userService, Permit permit) {
        this.userService = userService;
        this.permit = permit;
    }

    // Method to authorize a user for a given action on a resource
    private void authorize(User user, String action, Resource resource) {
        userService.authorize(user, action, resource);
    }

    // Authorizes a user to perform an action on a specific product
    private void authorize(User user, String action, Product product) {
        var attributes = new HashMap<String, Object>();
        attributes.put("vendor", product.getVendor());  // Add vendor attribute to the product
        userService.authorize(user, action, productResourceBuilder.withKey(product.getId().toString()).withAttributes(attributes).build());
    }

    // Authorizes a user to perform an action on a specific review
    private void authorize(User user, String action, Review review) {
        var attributes = new HashMap<String, Object>();
        attributes.put("customer", review.getCustomer());  // Add customer attribute to the review
        userService.authorize(user, action, reviewResourceBuilder.withKey(review.getId().toString()).withAttributes(attributes).build());
    }

    // Retrieves a product by its ID, throws an exception if not found
    private Product getProductById(int id) {
        return products.stream().filter(product -> product.getId().equals(id))
                .findFirst().orElseThrow(() -> new ResourceNotFoundException("Product with id " + id + " not found"));
    }

    // Retrieves all products, checks if the user is authorized to "read" products
    public List<Product> getAllProducts(User user) {
        authorize(user, "read", productResourceBuilder.build());  // User must have "read" permission
        return new ArrayList<>(products);  // Return a copy of the products list
    }

    // Retrieves a product by its ID, checks if the user is authorized to "read" the product
    public Product getProduct(User user, int id) {
        authorize(user, "read", productResourceBuilder.build());
        return getProductById(id);
    }

    // Adds a new product, authorizes the user and creates resource instances and role assignments in Permit
    public Product addProduct(User user, String content) {
        authorize(user, "create", productResourceBuilder.build());  // Check if user can create a product
        Product product = new Product(productIdCounter.incrementAndGet(), user.getKey(), content);  // Create new product

        try {
            // Create resource instance in Permit and assign "vendor" role to the user for this product
            permit.api.resourceInstances.create(new ResourceInstanceCreate(product.getId().toString(), "product").withTenant("default"));
            permit.api.roleAssignments.assign(new RoleAssignmentCreate("vendor", user.getKey()).withResourceInstance("product:" + product.getId()).withTenant("default"));
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException("Failed to create resource instance or role assignment: " + e.getMessage());
        }

        products.add(product);  // Add product to in-memory list
        return product;
    }

    // Updates a product's content, checks if the user is authorized to "update" the product
    public Product updateProduct(User user, int id, String content) {
        Product product = getProductById(id);  // Get the product by its ID
        authorize(user, "update", product);  // Check if user can update the product
        product.setContent(content);  // Update product content
        return product;
    }

    // Deletes a product, checks if the user is authorized to "delete" the product
    public void deleteProduct(User user, int id) {
        boolean isDeleted = products.removeIf(product -> {
            if (product.getId().equals(id)) {
                authorize(user, "delete", product);  // Check if user can delete the product
                return true;
            } else {
                return false;
            }
        });

        if (!isDeleted) {
            throw new ResourceNotFoundException("Product with id " + id + " not found");
        }

        try {
            permit.api.resourceInstances.delete("product:" + id);  // Remove product resource instance from Permit
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }
    }

    // Adds a review to a product, creates a resource instance and relationship in Permit
    public Review addReview(User user, int productId, String content) {
        authorize(user, "create", reviewResourceBuilder.build());  // Check if user can create a review
        Product product = getProductById(productId);  // Get the product by its ID
        Review review = new Review(reviewIdCounter.incrementAndGet(), user.getKey(), content);  // Create new review

        try {
            // Create a resource instance for the review and set relationship with the product
            permit.api.resourceInstances.create(new ResourceInstanceCreate(review.getId().toString(), "review").withTenant("default"));
            permit.api.relationshipTuples.create(new RelationshipTupleCreate("product:" + productId, "parent", "review:" + review.getId()));
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }

        product.addReview(review);  // Add the review to the product
        return review;
    }

    // Updates a review's content, checks if the user is authorized to "update" the review
    public Review updateReview(User user, int productId, int reviewId, String content) {
        Product product = getProductById(productId);  // Get the product by its ID
        Review review = product.getReviews().stream().filter(c -> c.getId().equals(reviewId))
                .findFirst().orElseThrow(() -> new ResourceNotFoundException("Review with id " + reviewId + " not found"));

        authorize(user, "update", review);  // Check if user can update the review
        review.setContent(content);  // Update review content
        return review;
    }

    // Deletes a review, checks if the user is authorized to "delete" the review
    public void deleteReview(User user, int productId, int reviewId) {
        Product product = getProductById(productId);  // Get the product by its ID
        boolean isDeleted = product.getReviews().removeIf(review -> {
            if (review.getId().equals(reviewId)) {
                authorize(user, "delete", review);  // Check if user can delete the review
                return true;
            } else {
                return false;
            }
        });

        if (!isDeleted) {
            throw new ResourceNotFoundException("Review with id " + reviewId + " not found");
        }

        try {
            permit.api.resourceInstances.delete("review:" + reviewId);  // Remove review resource instance from Permit
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }
    }
}

Then in the code below, the ProductController class handles HTTP requests related to products and their reviews. It exposes endpoints for managing products (like creating, updating, deleting, and retrieving) and for managing product reviews.

package com.boostmytool.store.controllers;

import com.boostmytool.store.model.Product;
import com.boostmytool.store.model.Review;
import com.boostmytool.store.service.ProductService;
import io.permit.sdk.enforcement.User;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController  // Indicates that this class is a Spring REST controller
@RequestMapping("/api/products")  // Base URL for all endpoints in this controller
public class ProductController {

    private final ProductService productService;  // ProductService instance to handle product-related operations

    @Autowired  // Autowires ProductService bean automatically
    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    // GET request to retrieve all products
    @GetMapping
    public List<Product> getAllProducts(HttpServletRequest request) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.getAllProducts(currentUser);  // Calls ProductService to get all products for the user
    }

    // GET request to retrieve a product by its ID
    @GetMapping("/{id}")
    public Product getProductById(HttpServletRequest request, @PathVariable("id") int id) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.getProduct(currentUser, id);  // Calls ProductService to get the product by ID for the user
    }

    // POST request to add a new product
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)  // Sets the response status to 201 (Created)
    public Product addProduct(HttpServletRequest request, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.addProduct(currentUser, content);  // Calls ProductService to add a new product
    }

    // PUT request to update an existing product by its ID
    @PutMapping("/{id}")
    public Product updateProduct(HttpServletRequest request, @PathVariable("id") int id, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.updateProduct(currentUser, id, content);  // Calls ProductService to update the product by ID
    }

    // DELETE request to delete a product by its ID
    @DeleteMapping("/{id}")
    public String deleteProduct(HttpServletRequest request, @PathVariable("id") int id) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        productService.deleteProduct(currentUser, id);  // Calls ProductService to delete the product by ID
        return "Deleted product with id " + id;  // Returns a success message after deletion
    }

    // POST request to add a new review to a product by product ID
    @PostMapping("/{id}/review")
    public Review addReview(HttpServletRequest request, @PathVariable("id") int id, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.addReview(currentUser, id, content);  // Calls ProductService to add a review to the product
    }

    // PUT request to update an existing review by product and review ID
    @PutMapping("/{id}/review/{reviewId}")
    public Review updateReview(HttpServletRequest request, @PathVariable("id") int id, @PathVariable("reviewId") int reviewId, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.updateReview(currentUser, id, reviewId, content);  // Calls ProductService to update the review
    }

    // DELETE request to delete a review by product and review ID
    @DeleteMapping("/{id}/review/{reviewId}")
    public String deleteReview(HttpServletRequest request, @PathVariable("id") int id, @PathVariable("reviewId") int reviewId) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        productService.deleteReview(currentUser, id, reviewId);  // Calls ProductService to delete the review
        return "Deleted review with id " + reviewId + " from product " + id;  // Returns a success message after deletion
    }
}

Step 2: Get your Environment API Key

In the UI Dashboard, copy the Environment API Key of the active environment.

Then add the env API key and PDP URL in the application.yaml file.

permit:
  pdpUrl: 'http://localhost:7766'
  apiKey: "Your Permit environment API Key"

Step 3: Deploy Policy Decision Point (PDP)

The Policy Decision Point (PDP) is deployed in your VPC and is in charge of evaluating your authorization requests. The PDP will ensure zero latency, great performance, high availability, and improved security.

Use the command below to pull the Permit.io PDP container from Docker Hub.

docker pull permitio/pdp-v2:latest

Then run the container.

docker run -it -p 7766:7000 --env PDP_DEBUG=True --env PDP_API_KEY=<YOUR_API_KEY> permitio/pdp-v2:latest

Step 4: Running the App

You can run the application using the following Gradle command:

./gradlew bootRun

Viewing and Creating Products

Let’s now interact with the application endpoints using REQBIN.

First, create a new user using the /api/users/signup endpoint.

curl -X POST "http://localhost:8080/api/users/signup" -H "Content-Type: application/json" -d 'johndoe'

You should be able to view the user in your Permit project, under Directory > All Tenants.

Initially, the user has no roles, so it cannot do much. For example, trying to list the products will result in a 403 Forbidden response, as shown below. The 403 error code means the user doesn’t have permissions to access the requested resource, which is products in this case. You can learn more about the difference between 401 and 403 error codes here.

For the user to view a list of products, assign them a viewer role using the command below:

curl -X POST "http://localhost:8080/api/users/assign-role" \
-H "Authorization: Bearer johndoe" \
-H "Content-Type: application/json" \
-d 'viewer'

You should see that user johndoe was assigned role viewer, as shown below:

Since a viewer can create a product, use the command below to create a product with user johndoe.

curl -X POST "http://localhost:8080/api/products" -H "Authorization: Bearer johndoe" -H "Content-Type: application/json" -d 'MacBook'

You should see that a new product is created with ID 1 and that the user johndoe has been added as the vendor.

Adding Reviews To Products

To add reviews to products, create another user called jane.

curl -X POST "http://localhost:8080/api/users/signup" -H "Content-Type: application/json" -d 'jane'

For the user to add a review to products, assign them a viewer role using the command below:

curl -X POST "http://localhost:8080/api/users/assign-role" \
-H "Authorization: Bearer jane" \
-H "Content-Type: application/json" \
-d 'viewer'

Then you can add a review to the product added by johndoe using the command below:

curl -X POST "http://localhost:8080/api/products/1/review" -H "Authorization: Bearer jane" -H "Content-Type: application/json" -d 'The product was in good quality'

Congratulations! You’ve completed the project for this tutorial.

Next Steps

Now that you've learned how to implement fine-grained authorization in your Java and Spring Boot applications using Permit.io, you might want to explore further.

Here are some valuable resources:

• Permit.io docs

• RBAC VS ABAC: Choosing the Right Authorization Policy Model

Before We End

I hope you found this tutorial insightful.

Here are some of my other recent blog posts that you might enjoy:

• Learn React – A Guide to the Key Concepts

• Neon Postgres vs Supabase

• Full Stack Development with Next.js, Clerk, and Neon Postgres

For more tutorials on amazing developer tools, be sure to check out my blog DTA.

Follow me on Twitter to get live updates on my other projects.

Happy coding.

Major browsers, such as Chrome, Firefox, and Edge, continuously update their developer tools, with each update potentially bringing new features to web developers. These new features increase the ease of use by adding intuitive UIs, more advanced debugging, and enhanced performance analysis tools.

Staying up to date with these changes lets you use your browser DevTools to its fullest potential to make your workflow easier and speed up the delivery of your web applications.

Table of Content

• How to Use Scroll Into View in DevTools

• How to Use Console Shortcuts in DevTools

• How to Block Resource Request for Website Testing in DevTools

• How to Edit and Resend Network Request in DevTools

• How to Detect Unused Source Code in DevTools

• How to Enable Accessibility Tree in DevTools

• Summary

In this article, we’ll discover some good cross-browser DevTools features and discuss how to use them.

Let’s get started!

How to Use Scroll Into View in DevTools

When debugging, there may be a lot of HTML nodes to skim through to find out where your issue is. Most of the time, when you find the node, you won’t see it until you scroll to where it is on the page.

The Scroll Into View feature easily brings the DOM node into the viewport by right-clicking and selecting Scroll Into view in Chrome, Firefox, and Edge.

This feature saves a lot of time when debugging CSS issues or wanting to verify the correct placement of elements on a page, ensuring you can quickly locate elements on the page through the HTML nodes without needing to scroll through many lines of content manually.

In the image below, we are trying to find a h2 element that is nested inside several layers of other elements.

In the image above, instead of scrolling through the entire page to spot the h2 element, we right-clicked and used the Scroll Into View feature to instantly bring the h2 element into view. We can expand on this feature to do other things with the element when we have scrolled to it. We can tweak the CSS properties in real time via the styles panel and even find and fix layout issues.

How to Use Console Shortcuts in DevTools

There are lots of shortcuts that can be used in the Console that allows you, as the developer, to debug faster. One of them is the $_ shortcut. This shortcut returns the value of the most recent expression evaluated by the Console. Let’s say, for example, we have a multiplier function:

In the image below, you can see how the $_ shortcut is used as a special variable in the browser Console to store the most recently evaluated expression:

Without the $_ shortcut, you would have to either retype the entire function call or you might store the result in a variable like this:

let result = multiply(5)
result(4) // returns 20

In the code above, the multiply(5) function has to return a function and assign the function to result, which is then called with 4 as the parameter result(4).

I'm sure you can see how this already introduces some redundancy and extra steps that can be cumbersome when you're dealing with more complex operations or when doing multiple steps of calculations. This is where the $_ shortcut shines. When we run the multiply(5) code in the Console, a function is returned and stored in the $_ variable by the Console, which we can access using the $_ shortcut.

Another shortcut is using $0 to access nodes from the Console. $0 can be used to access the currently selected node in the DOM tree from within the Console. As you inspect a webpage with DevTools, you often browse the DOM tree in the Elements panel to find the element that you're interested in. Once you click on an element in this panel, DevTools internally keeps track of this element, and it becomes the currently selected element.

The $0 is a shortcut that refers to the currently selected element in the Console, so you can manipulate it directly in the Console without writing a query to select it again.

The screenshot below shows how we can use $0 in the Console to access the selected node in the DOM tree and change the background color to whatever we want.

From the image above, we started by inspecting the desired element we wanted in the elements panel. Now, instead of querying the element again using document.querySelector('#element'), you can just use $0 to manipulate it directly like this:

$0.style.backgroundColor = 'lightblue';

This code changes the background color of the selected <div> to a gentle light blue. What really makes $0 useful in this case is that it allows you to refer directly to the exact element you chose in the DOM, making sure that you're working with the correct element, even in cases where elements are dynamically generated or deeply nested.

How to Block Resource Request for Website Testing in DevTools

The Block Resource Request DevTools feature is an important feature for web developers to test how their websites behave when specific resources cannot be loaded.

This feature enables you to simulate situations where an image, JavaScript, CSS, or an entire domain becomes unreachable, and you get to see how your webpage would behave in that situation.

Resources requested by the browser aren’t always guaranteed to be downloaded, which can lead to unexpected experiences for users of your website. You can block requests to a resource on Chrome, Firefox, and Edge and test how your site behaves.

On Chrome and Edge:

• On the Network panel, right-click on the resource you want to block and select Block request URL.

• Refresh the website, and the blocked resource won’t be downloaded and won’t affect the webpage.

In the image below, we are using the Block request URL option in the Network tab to block a CSS request and see how the web page will look like if the selected CSS file fails to load.

From the image above, we can see all the network requests made by the webpage including requests for images, CSS files, JavaScript files, and so on. In my case I've filtered for just CSS files to be shown only.

From here, you can right-click on the CSS file in the Network panel and select Block request URL. This action will prevent the browser from loading the specific CSS file the next time the page is refreshed.

By blocking the request, we can watch out for weird behaviors and also measure how the absence of the blocked resource can affect the page load time and performance.

On Firefox:

• On the Network panel, right-click on the resource you want to block and select Block URL.

• Reload the page.

I’ve used this to test how my site behaves when I don’t load a particular JavaScript file. This feature can help developers debug issues that can arise when users disable JavaScript.

How to Edit and Resend Network Request in DevTools

One of the coolest DevTools features is the ability to edit and resend network requests right in the browser. This feature can be really useful for debugging a network request problem. For example, scenarios where you’d want to see how changes to request parameters, headers, or body affect the response from the server, without having to make any changes to the frontend code or restarting the entire request process.

When making a network request, requests made to a backend service might fail or not respond with the intended data. It’s a pain to have to reload the whole page to retry the request, which is why the Edit and Resend feature is helpful.

In the Edge and Firefox browser, you can edit and resend a network request by right-clicking on the request you want to edit or resend and select Edit and Resend, just like in the image below.

In the image above, we tried to log into a website. When a user submits their credentials, the form sends a POST request to an API endpoint, /auth/login, with the user’s username and password.

Sometimes, the server may return a 400 Bad Request error, and for us to debug the error and find out why, we have to retry the request. We don't want to keep on filling out the form, so we use the Edit and Resend feature as shown below.

The image above is the network Console or a sidebar that will open when you click on Edit and Resend, showing the details of the request. Here, you can edit:

• URL: If necessary, you can modify the URL or add query parameters.

• Headers: You might notice a missing or incorrect Content-Type header, which you can fix here.

• Body: This is where you can adjust the payload, such as correcting the username or password fields.

In Chrome browsers, the edit and resend feature only works for XHR requests, and you can use it by right-clicking on the request and selecting replay.

How to Detect Unused Source Code in DevTools

The Coverage tool in DevTools enables developers to spot areas of their JavaScript and CSS files that remain unused during the loading and interaction stages of a webpage. It's an important feature for enhancing web performance by reducing file sizes and eliminating unnecessary code for faster page load times and a better user experience.

Removing unused JS and CSS code is a great way to save your users bandwidth. The Coverage tool allows you to find the unused code in your source code, and either remove it or defer it till the piece of code is needed.

On Chrome and Edge:

• In DevTools, press Ctrl/cmd+Shift+P, type coverage and select Start instrumenting coverage, refresh the page, then hit enter.

• You’ll see a table of JS and CSS files with an unused byte column.

• Click on any of the files to open it. The line by the side indicates which section of code isn’t unused in red.

In the image below, we are identifying the unused CSS code to potentially remove or defer the loading of the code.

From the image above, after the recording is complete, the Coverage tool will display a list of CSS and JavaScript files loaded by the page, along with detailed metrics:

• Total Bytes: The size of the file.

• Unused Bytes: The number of bytes in the file that were not used.

• Usage Visualization: A visual bar representing the proportion of used versus unused code.

On Safari: In the Sources panel, open the left navigation sidebar and click on any JS file. At the top right of the toolbar, click on the coverage icon c and refresh your page. You'd be able to see that the sections of code not executed are grayed out.

How to Enable Accessibility Tree in DevTools

The accessibility tree is similar to the element DOM tree and is used by assistive technologies such as screen readers to read web content. Developers can use this feature to debug accessibility issues on their websites. Chromium browsers use Chrome’s accessibility API to make this possible, while Firefox has its own accessibility tool.

On Chrome and Edge:

• On the settings page, select the Experiments tab.

• Check the box for the Enable full accessibility tree view option in the Elements panel.

• Refresh DevTools and go to the Elements tool.

• In the top-right corner of the element view, click Switch to DOM Tree view.

For example, in the image below, we are checking if the links and buttons on our website are recognized correctly and accessible to users who rely on screen readers:

With the accessibility tree enabled, you can see a simplified version of the DOM tree, focused on elements relevant for accessibility. When you select an element on the accessibility tree to view its properties, the tree displays the element’s role, name, and other important attributes, such as aria-label if they are present.

You’ll also see if the element is focusable and what its computed accessibility properties are.

This helps a great deal because if the element isn’t appearing correctly in the accessibility tree or is missing essential attributes, you may need to adjust your HTML or ARIA attributes to improve accessibility.

On Firefox:

• In the Firefox DevTools, click on the accessibility tab and expand the document node.

• You can click on different nodes to view their properties.

• Accessibility issues for nodes will be displayed on the Checks tab.

Summary

In a nutshell, staying current with the latest cross-browser DevTools features will save you time as a web developer. This post touches on element inspection tips, some Console shortcuts to make your debugging process easier, and some useful tips for network monitoring.

Hopefully, you will keep exploring and using more DevTools features to improve your developer experience.

And building a project like a video conferencing app from scratch can feel even more overwhelming, especially with the complexities of managing video streams, user auth, and real-time interactions.

But what if I told you there’s an easier way to do this – one that lets you build your video conferencing app in a fraction of the time?

In this article, I’ll show you how I built a video conferencing app using Stream and Clerk in Next.js.

Here is the source code (remember to give it a star ⭐).

Before we start, let me tell you why I wrote this tutorial.

I’m a Software Engineer who cares about writing and I love to code, design, develop, and then teach people.

I've been using open-source projects, products, and services for a while now, and contributing to many of them to improve them how I can. Last month I built an open-source blog for “awesome developer tools“ called - devtoolsacademy

This article is about sharing the experience I’ve had using yet another awesome developer tool.

Table of Contents:

• What is Stream?

• Prerequisites

• How to Build the App Interface with Next.js

  • The Create Link Modal

  • The Instant Meeting Modal

  • The Join Meeting Modal

• How to Authenticate Users with Clerk

• How to Set Up Stream in a Next.js app

• How to Create and Join Calls with Stream

  • Creating and Scheduling calls

  • Joining calls and the Meeting Page

  • Retrieving Upcoming Calls

• Next Steps

What is Stream?

Stream is an open-source cloud-based platform that provides APIs and SDKs for building scalable and feature-rich real-time applications. It offers pre-built UI components for creating enterprise-grade software apps with features like chat, video, audio, and activity feeds.

Here's how I'll use Stream while building the app:

• Set up real-time video and audio calls

• Use Stream's UI components to quickly build the interface

• Implement key features like video and audio calls

• Call Types – I'll implement instant meetings and pre-scheduled calls using Stream

• Leverage Stream's call and participant objects to manage call state

Prerequisites

To fully understand the tutorial, you need to have a basic understanding of React and Next.js. You’ll also need the following:

• Stream React SDK - provides pre-built UI components for adding video call features quickly.

• Stream Node.js SDK - for managing server-side interactions and keeping Stream's state in sync.

• Clerk - a comprehensive user management platform to handle authentication effortlessly.

• Headless UI - provides accessible UI components for building user-friendly applications.

• React Copy-to-Clipboard - allows users to easily copy meeting links within the app.

• React Icons - offers a library of easily integrated icons.

How to Build the App Interface with Next.js

In this section, I'll guide you through creating the user interface for the video-conferencing app. The interface will allow users to easily create, join, and schedule meetings, as well as view their upcoming meetings.

First, let’s create a Next.js TypeScript project by running the code snippet below:

npx create-next-app facetime-app

Then install the following packages:

• React icons - a popular React icons package

• Headless UI - provides a set of accessible UI components

• React-copy-to-clipboard - a lightweight package that enables us to copy meeting links.

npm install react-icons @headlessui/react react-copy-to-clipboard

Copy the code snippet below into the app/page.tsx file:

"use client";
import { useState } from "react";
import { FaLink, FaVideo } from "react-icons/fa";
import InstantMeeting from "@/app/modals/InstantMeeting";
import UpcomingMeeting from "@/app/modals/UpcomingMeeting";
import CreateLink from "@/app/modals/CreateLink";
import JoinMeeting from "@/app/modals/JoinMeeting";

export default function Dashboard() {
    const [startInstantMeeting, setStartInstantMeeting] =
        useState<boolean>(false);
    const [joinMeeting, setJoinMeeting] = useState<boolean>(false);
    const [showUpcomingMeetings, setShowUpcomingMeetings] =
        useState<boolean>(false);
    const [showCreateLink, setShowCreateLink] = useState<boolean>(false);

    return (
        <>
            <button
                className=' top-5 right-5 text-sm fixed bg-green-500 px-2 w-[150px] hover:bg-green-600 py-3 flex flex-col items-center text-white rounded-md shadow-sm cursor-pointer z-10'
                onClick={() => setJoinMeeting(true)}
            >
                <FaVideo className='mb-[3px] text-white' />
                Join FaceTime
            </button>

            <main className='w-full h-screen flex flex-col items-center justify-center'>
                <h1 className='font-bold text-2xl text-center'>FaceTime</h1>
                <div className='flex flex-col'>
                    <button
                        className='text-green-500 underline text-sm text-center cursor-pointer'
                        onClick={() => setShowUpcomingMeetings(true)}
                    >
                        Upcoming FaceTime
                    </button>
                </div>

                <div className='flex items-center justify-center space-x-4 mt-6'>
                    <button
                        className='bg-gray-500 px-4 w-[200px] py-3 flex flex-col items-center hover:bg-gray-600 text-white rounded-md shadow-sm'
                        onClick={() => setShowCreateLink(true)}
                    >
                        <FaLink className='mb-[3px] text-gray-300' />
                        Create link
                    </button>
                    <button
                        className='bg-green-500 px-4 w-[200px] hover:bg-green-600 py-3 flex flex-col items-center text-white rounded-md shadow-sm'
                        onClick={() => setStartInstantMeeting(true)}
                    >
                        <FaVideo className='mb-[3px] text-white' />
                        New FaceTime
                    </button>
                </div>
            </main>

            {startInstantMeeting && (
                <InstantMeeting
                    enable={startInstantMeeting}
                    setEnable={setStartInstantMeeting}
                />
            )}
            {showUpcomingMeetings && (
                <UpcomingMeeting
                    enable={showUpcomingMeetings}
                    setEnable={setShowUpcomingMeetings}
                />
            )}
            {showCreateLink && (
                <CreateLink enable={showCreateLink} setEnable={setShowCreateLink} />
            )}
            {joinMeeting && (
                <JoinMeeting enable={joinMeeting} setEnable={setJoinMeeting} />
            )}
        </>
    );
}

The code snippet above renders multiple buttons that allow users to perform actions like joining, creating, and scheduling a call. Each button opens a modal that prompts the user to provide additional details specific to the action they are performing.

Next, let’s create a modals folder within the Next.js app directory and add the following components to the modals folder:

cd app
mkdir modals && cd modals
touch CreateLink.tsx InstantMeeting.tsx JoinMeeting.tsx UpcomingMeeting.tsx

The CreateLink modal allows users to provide a description and schedule a time for the call. The InstantMeeting modal lets users start an instant meeting by providing a call description. The JoinMeeting modal enables users to enter a call link and join a meeting. And the UpcomingMeeting modal displays all scheduled upcoming calls.

The Create Link Modal

Copy the code snippet below into the CreateLink modal:

"use client";
import {
    Dialog,
    DialogTitle,
    DialogPanel,
    Transition,
    Description,
    TransitionChild,
} from "@headlessui/react";
import { Fragment, SetStateAction, useState, Dispatch } from "react";
import CopyToClipboard from "react-copy-to-clipboard";
import { FaCopy } from "react-icons/fa";

export default function CreateLink({ enable, setEnable }: Props) {
    const [showMeetingLink, setShowMeetingLink] = useState(false);
    const [facetimeLink, setFacetimeLink] = useState<string>("");
    const closeModal = () => setEnable(false);

    return (
        <>
            <Transition appear show={enable} as={Fragment}>
                <Dialog as='div' className='relative z-10' onClose={closeModal}>
                    <TransitionChild
                        as={Fragment}
                        enter='ease-out duration-300'
                        enterFrom='opacity-0'
                        enterTo='opacity-100'
                        leave='ease-in duration-200'
                        leaveFrom='opacity-100'
                        leaveTo='opacity-0'
                    >
                        <div className='fixed inset-0 bg-black/75' />
                    </TransitionChild>

                    <div className='fixed inset-0 overflow-y-auto'>
                        <div className='flex min-h-full items-center justify-center p-4 text-center'>
                            <TransitionChild
                                as={Fragment}
                                enter='ease-out duration-300'
                                enterFrom='opacity-0 scale-95'
                                enterTo='opacity-100 scale-100'
                                leave='ease-in duration-200'
                                leaveFrom='opacity-100 scale-100'
                                leaveTo='opacity-0 scale-95'
                            >
                                <DialogPanel className='w-full max-w-2xl transform overflow-hidden rounded-2xl bg-white p-6 align-middle shadow-xl transition-all text-center'>
                                    {showMeetingLink ? (
                                        <MeetingLink facetimeLink={facetimeLink} />
                                    ) : (
                                        <MeetingForm
                                            setShowMeetingLink={setShowMeetingLink}
                                            setFacetimeLink={setFacetimeLink}
                                        />
                                    )}
                                </DialogPanel>
                            </TransitionChild>
                        </div>
                    </div>
                </Dialog>
            </Transition>
        </>
    );
}

The code snippet above renders a form that allows users to input a description and select a time to schedule a call. Once the call is created, the generated link is displayed and can be copied.

Finally, add the MeetingForm and MeetingLink components below the CreateLink component:

const MeetingForm = ({
    setShowMeetingLink,
    setFacetimeLink,
}: {
    setShowMeetingLink: React.Dispatch<SetStateAction<boolean>>;
    setFacetimeLink: Dispatch<SetStateAction<string>>;
}) => {
    const [description, setDescription] = useState<string>("");
    const [dateTime, setDateTime] = useState<string>("");

    const handleStartMeeting = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        console.log({ description, dateTime });
    };

    return (
        <>
            <DialogTitle
                as='h3'
                className='text-lg font-bold leading-6 text-green-600'
            >
                Schedule a FaceTime
            </DialogTitle>

            <Description className='text-xs opacity-40 mb-4'>
                Schedule a FaceTime meeting with your cliq
            </Description>

            <form className='w-full' onSubmit={handleStartMeeting}>
                <label
                    className='block text-left text-sm font-medium text-gray-700'
                    htmlFor='description'
                >
                    Meeting Description
                </label>
                <input
                    type='text'
                    name='description'
                    id='description'
                    value={description}
                    onChange={(e) => setDescription(e.target.value)}
                    className='mt-1 block w-full text-sm py-3 px-4 border-gray-200 border-[1px] rounded mb-3'
                    required
                    placeholder='Enter a description for the meeting'
                />

                <label
                    className='block text-left text-sm font-medium text-gray-700'
                    htmlFor='date'
                >
                    Date and Time
                </label>

                <input
                    type='datetime-local'
                    id='date'
                    name='date'
                    required
                    className='mt-1 block w-full text-sm py-3 px-4 border-gray-200 border-[1px] rounded mb-3'
                    value={dateTime}
                    onChange={(e) => setDateTime(e.target.value)}
                />

                <button className='w-full bg-green-600 text-white py-3 rounded mt-4'>
                    Create FaceTime
                </button>
            </form>
        </>
    );
};

The MeetingForm component accepts the call description and scheduled time, while the MeetingLink component displays the generated call link and allows users to copy it.

const MeetingLink = ({ facetimeLink }: { facetimeLink: string }) => {
    const [copied, setCopied] = useState<boolean>(false);
    const handleCopy = () => setCopied(true);

    return (
        <>
            <DialogTitle
                as='h3'
                className='text-lg font-bold leading-6 text-green-600'
            >
                Copy FaceTime Link
            </DialogTitle>

            <Description className='text-xs opacity-40 mb-4'>
                You can share the facetime link with your participants
            </Description>

            <div className='bg-gray-100 p-4 rounded flex items-center justify-between'>
                <p className='text-xs text-gray-500'>
                    {`${process.env.NEXT_PUBLIC_FACETIME_HOST}/${facetimeLink}`}
                </p>

                <CopyToClipboard
                    onCopy={handleCopy}
                    text={`${process.env.NEXT_PUBLIC_FACETIME_HOST}/${facetimeLink}`}
                >
                    <FaCopy className='text-green-600 text-lg cursor-pointer' />
                </CopyToClipboard>
            </div>

            {copied && (
                <p className='text-red-600 text-xs mt-2'>Link copied to clipboard</p>
            )}
        </>
    );
};

The Instant Meeting Modal

Copy the following code snippet into the InstantMeeting modal:

"use client";
import {
    Dialog,
    DialogTitle,
    DialogPanel,
    Transition,
    Description,
    TransitionChild,
} from "@headlessui/react";
import { FaCopy } from "react-icons/fa";
import CopyToClipboard from "react-copy-to-clipboard";
import { Fragment, useState, Dispatch, SetStateAction } from "react";
import { useStreamVideoClient } from "@stream-io/video-react-sdk";
import { useUser } from "@clerk/nextjs";
import Link from "next/link";

export default function InstantMeeting({ enable, setEnable }: Props) {
    const [showMeetingLink, setShowMeetingLink] = useState(false);
    const [facetimeLink, setFacetimeLink] = useState<string>("");

    const closeModal = () => setEnable(false);

    return (
        <>
            <Transition appear show={enable} as={Fragment}>
                <Dialog as='div' className='relative z-10' onClose={closeModal}>
                    <TransitionChild
                        as={Fragment}
                        enter='ease-out duration-300'
                        enterFrom='opacity-0'
                        enterTo='opacity-100'
                        leave='ease-in duration-200'
                        leaveFrom='opacity-100'
                        leaveTo='opacity-0'
                    >
                        <div className='fixed inset-0 bg-black/75' />
                    </TransitionChild>

                    <div className='fixed inset-0 overflow-y-auto'>
                        <div className='flex min-h-full items-center justify-center p-4 text-center'>
                            <TransitionChild
                                as={Fragment}
                                enter='ease-out duration-300'
                                enterFrom='opacity-0 scale-95'
                                enterTo='opacity-100 scale-100'
                                leave='ease-in duration-200'
                                leaveFrom='opacity-100 scale-100'
                                leaveTo='opacity-0 scale-95'
                            >
                                <DialogPanel className='w-full max-w-2xl transform overflow-hidden rounded-2xl bg-white p-6 align-middle shadow-xl transition-all text-center'>
                                    {showMeetingLink ? (
                                        <MeetingLink facetimeLink={facetimeLink} />
                                    ) : (
                                        <MeetingForm
                                            setShowMeetingLink={setShowMeetingLink}
                                            setFacetimeLink={setFacetimeLink}
                                        />
                                    )}
                                </DialogPanel>
                            </TransitionChild>
                        </div>
                    </div>
                </Dialog>
            </Transition>
        </>
    );
}

The code snippet above renders a form that allows users to provide a call description. Once the call is created, the link is generated and available to be copied before starting the call.

Finally, add the MeetingForm and MeetingLink components below the CreateLink component:

const MeetingForm = ({
    setShowMeetingLink,
    setFacetimeLink,
}: {
    setShowMeetingLink: Dispatch<SetStateAction<boolean>>;
    setFacetimeLink: Dispatch<SetStateAction<string>>;
}) => {
    const [description, setDescription] = useState<string>("");

    const handleStartMeeting = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        console.log({ description });
    };

    return (
        <>
            <DialogTitle
                as='h3'
                className='text-lg font-bold leading-6 text-green-600'
            >
                Create Instant FaceTime
            </DialogTitle>

            <Description className='text-xs opacity-40 mb-4'>
                You can start a new FaceTime instantly.
            </Description>

            <form className='w-full' onSubmit={handleStartMeeting}>
                <label
                    className='block text-left text-sm font-medium text-gray-700'
                    htmlFor='description'
                >
                    Meeting Description
                </label>
                <input
                    type='text'
                    name='description'
                    id='description'
                    value={description}
                    required
                    onChange={(e) => setDescription(e.target.value)}
                    className='mt-1 block w-full text-sm py-3 px-4 border-gray-200 border-[1px] rounded mb-3'
                    placeholder='Enter a description for the meeting'
                />

                <button className='w-full bg-green-600 text-white py-3 rounded mt-4'>
                    Proceed
                </button>
            </form>
        </>
    );
};

The MeetingForm component accepts the call description, while the MeetingLink component displays the generated call link and allows users to copy it before starting the call.

The Join Meeting Modal

Copy the code snippet below into the JoinMeeting.tsx file. It renders a form that accepts the call link and redirects users to the call page.

"use client";
import {
    Dialog,
    DialogTitle,
    DialogPanel,
    Transition,
    TransitionChild,
} from "@headlessui/react";
import { useRouter } from "next/navigation";
import { Fragment, useState } from "react";

export default function JoinMeeting({ enable, setEnable }: Props) {
    const closeModal = () => setEnable(false);

    return (
        <>
            <Transition appear show={enable} as={Fragment}>
                <Dialog as='div' className='relative z-10' onClose={closeModal}>
                    <TransitionChild
                        as={Fragment}
                        enter='ease-out duration-300'
                        enterFrom='opacity-0'
                        enterTo='opacity-100'
                        leave='ease-in duration-200'
                        leaveFrom='opacity-100'
                        leaveTo='opacity-0'
                    >
                        <div className='fixed inset-0 bg-black/75' />
                    </TransitionChild>

                    <div className='fixed inset-0 overflow-y-auto'>
                        <div className='flex min-h-full items-center justify-center p-4 text-center'>
                            <TransitionChild
                                as={Fragment}
                                enter='ease-out duration-300'
                                enterFrom='opacity-0 scale-95'
                                enterTo='opacity-100 scale-100'
                                leave='ease-in duration-200'
                                leaveFrom='opacity-100 scale-100'
                                leaveTo='opacity-0 scale-95'
                            >
                                <DialogPanel className='w-full max-w-2xl transform overflow-hidden rounded-2xl bg-white p-6 align-middle shadow-xl transition-all text-center'>
                                    <CallLinkForm />
                                </DialogPanel>
                            </TransitionChild>
                        </div>
                    </div>
                </Dialog>
            </Transition>
        </>
    );
}

Add the CallLinkForm below the JoinMeeting component:

const CallLinkForm = () => {
    const [link, setLink] = useState<string>("");
    const router = useRouter();

    const handleJoinMeeting = (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        router.push(`${link}`);
    };

    return (
        <>
            <DialogTitle
                as='h3'
                className='text-lg font-bold leading-6 text-green-600'
            >
                Join FaceTime
            </DialogTitle>

            <form className='w-full' onSubmit={handleJoinMeeting}>
                <label
                    className='block text-left text-sm font-medium text-gray-700'
                    htmlFor='link'
                >
                    Enter the FaceTime link
                </label>
                <input
                    type='url'
                    name='link'
                    id='link'
                    value={link}
                    onChange={(e) => setLink(e.target.value)}
                    className='mt-1 block w-full text-sm py-3 px-4 border-gray-200 border-[1px] rounded mb-3'
                    placeholder='Enter the FaceTime link'
                />

                <button className='w-full bg-green-600 text-white py-3 rounded mt-4'>
                    Join now
                </button>
            </form>
        </>
    );
};

Congratulations! You’ve completed the app’s interface.

How to Authenticate Users with Clerk

Clerk is a user management platform that enables you to add auth to web apps.

You can install the Clerk Next.js SDK by running the following code snippet in your terminal:

npm install @clerk/nextjs

Create a middleware.ts file within the Next.js src folder and copy the code snippet below into the file:

import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";

const protectedRoutes = createRouteMatcher([
    "/facetime(.*)",
    "/dashboard",
    "/",
]);

//👇🏻 protects the route
export default clerkMiddleware((auth, req) => {
    if (protectedRoutes(req)) {
        auth().protect();
    }
});

export const config = {
    matcher: ["/((?!.*\\\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
};

The createRouteMatcher function accepts an array containing routes to be protected from unauthenticated users and the clerkMiddleware() function ensures the routes are protected.

Next, import the following Clerk components into the app/layout.tsx file and update the RootLayout function as shown below:

import {
    ClerkProvider,
    SignInButton,
    SignedIn,
    SignedOut,
    UserButton,
} from "@clerk/nextjs";
import "./globals.css";

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <ClerkProvider>
            <html lang='en'>
                <body className={inter.className}>
                    <nav className='w-full py-4 md:px-8 px-4 text-center flex items-center justify-between sticky top-0 bg-white '>
                        <div className='flex items-center justify-end gap-5'>
                            {/*-- if user is signed out --*/}
                            <SignedOut>
                                <SignInButton mode='modal' />
                            </SignedOut>
                            {/*-- if user is signed in --*/}
                            <SignedIn>
                                <UserButton />
                            </SignedIn>
                        </div>
                    </nav>

                    {children}
                </body>
            </html>
        </ClerkProvider>
    );
}

After completing this, users will be prompted to create an account or sign in before they can access the application pages.

Finally, create a Clerk account and set up a new Clerk application. Add your Clerk publishable and secret keys to the .env.local file in your project.

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=<publishable_key>
CLERK_SECRET_KEY=<secret_key>

How to Set Up Stream in a Next.js app

First, create a Stream account and set up an organization to house your app. Then, copy the following credentials into your .env.local file:

STREAM_APP_ID=<your_app_id>
NEXT_PUBLIC_STREAM_API_KEY=<your_stream_api_key>
STREAM_SECRET_KEY=<your_stream_secret_key>
NEXT_PUBLIC_FACETIME_HOST=http://localhost:3000/facetime

Next, install Stream React Video SDK and the Stream Node.js SDK.

npm install @stream-io/video-react-sdk @stream-io/node-sdk

Create a providers folder containing a StreamVideoProvider.tsx file and copy the following code snippet into the file:

"use client";
import { tokenProvider } from "@/actions/stream.actions";
import { StreamVideo, StreamVideoClient } from "@stream-io/video-react-sdk";
import { useState, ReactNode, useEffect } from "react";
import { useUser } from "@clerk/nextjs";

const apiKey = process.env.NEXT_PUBLIC_STREAM_API_KEY!;

export const StreamVideoProvider = ({ children }: { children: ReactNode }) => {
    const [videoClient, setVideoClient] = useState<StreamVideoClient>();

    const { user, isLoaded } = useUser();

    useEffect(() => {
        if (!isLoaded || !user || !apiKey) return;
        if (!tokenProvider) return;
        const client = new StreamVideoClient({
            apiKey,
            user: {
                id: user?.id,
                name: user?.primaryEmailAddress?.emailAddress,
                image: user?.imageUrl,
            },
            tokenProvider, //👉🏻 pending creation
        });

        setVideoClient(client);
    }, [user, isLoaded]);

    if (!videoClient) return null;

    return <StreamVideo client={videoClient}>{children}</StreamVideo>;
};

Let’s wrap the entire app with the StreamVideoProvider component, which initializes a Stream client to identify each user.

The StreamVideoClient function takes an object containing the API key, the user object with details from Clerk, and a tokenProvider.

Next, let’s create a Next.js server action (tokenProvider) that generates the token.

Create an actions folder, add a stream.actions.ts file, and copy the following code snippet into the file:

//👇🏻 tokenPrvoider function
"use server";

import { currentUser } from "@clerk/nextjs/server";
import { StreamClient } from "@stream-io/node-sdk";

const STREAM_API_KEY = process.env.NEXT_PUBLIC_STREAM_API_KEY!;
const STREAM_API_SECRET = process.env.STREAM_SECRET_KEY!;

export const tokenProvider = async () => {
    const user = await currentUser();

    if (!user) throw new Error("User is not authenticated");
    if (!STREAM_API_KEY) throw new Error("Stream API key secret is missing");
    if (!STREAM_API_SECRET) throw new Error("Stream API secret is missing");

    const streamClient = new StreamClient(STREAM_API_KEY, STREAM_API_SECRET);

    const expirationTime = Math.floor(Date.now() / 1000) + 3600;
    const issuedAt = Math.floor(Date.now() / 1000) - 60;

    //👇🏻 generates a Stream user token
    const token = streamClient.generateUserToken({
        user_id: user.id,
        exp: expirationTime,
        validity_in_seconds: issuedAt,
    });
    //👇🏻 returns the user token
    return token;
};

Finally, update the RootLayout function in the app/layout.tsx file by wrapping the entire application with the StreamVideoProvider component:

import "@stream-io/video-react-sdk/dist/css/styles.css";
import { StreamVideoProvider } from "./providers/StreamVideoProvider";

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <ClerkProvider>
            <html lang='en'>
                <body className={inter.className}>
                    <StreamVideoProvider>
                        <nav className='w-full py-4 md:px-8 px-4 text-center flex items-center justify-between sticky top-0 bg-white '>
                            <div className='flex items-center justify-end gap-5'>
                                {/*-- if user is signed out --*/}
                                <SignedOut>
                                    <SignInButton mode='modal' />
                                </SignedOut>
                                {/*-- if user is signed in --*/}
                                <SignedIn>
                                    <UserButton />
                                </SignedIn>
                            </div>
                        </nav>

                        {children}
                    </StreamVideoProvider>
                </body>
            </html>
        </ClerkProvider>
    );
}

Congratulations! You've successfully integrated Stream into the Next.js app.

How to Create and Join Calls with Stream

In this section, you'll learn how to create, schedule, and join calls using the Stream SDK. You'll also learn how to set up the meeting room with the necessary components and fetch upcoming calls from Stream.

Creating and Scheduling calls

To create an instant meeting, execute the handleStartMeeting function. It generates a random ID for the call and creates the meeting using the current date and the provided description.

import { useStreamVideoClient } from "@stream-io/video-react-sdk";
import { useUser } from "@clerk/nextjs";
const client = useStreamVideoClient();
const { user } = useUser();

const handleStartMeeting = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    if (!client || !user) return;
    try {
        const id = crypto.randomUUID();
        const call = client.call("default", id);
        if (!call) throw new Error("Failed to create meeting");

        await call.getOrCreate({
            data: {
                starts_at: new Date(Date.now()).toISOString(),
                custom: {
                    description,
                },
            },
        });

        setFacetimeLink(`${call.id}`);
        setShowMeetingLink(true);
    } catch (error) {
        console.error(error);
        alert("Failed to create Meeting");
    }
};

The call.getOrCreate() function accepts an optional call description along with the current date and time to initiate the call.

It also allows you to schedule calls for a specific time in the future. In this case, you can specify the desired date and time, and Stream will automatically schedule the call for that period.

import { useStreamVideoClient } from "@stream-io/video-react-sdk";
import { useUser } from "@clerk/nextjs";
const client = useStreamVideoClient();
const { user } = useUser();

const handleScheduleMeeting = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    if (!client || !user) return;
    try {
        const id = crypto.randomUUID();
        const call = client.call("default", id);
        if (!call) throw new Error("Failed to create meeting");

        await call.getOrCreate({
            data: {
                //👇🏻 only necessary changes
                starts_at: new Date(dateTime).toISOString(),
                custom: {
                    description,
                },
            },
        });
        setFacetimeLink(`${call.id}`);
        setShowMeetingLink(true);
    } catch (error) {
        console.error(error);
        console.error("Failed to create Meeting");
    }
};

Joining calls and the Meeting Page

Recall that the meeting link in the app is declared as:

`${process.env.NEXT_PUBLIC_FACETIME_HOST}/${facetimeLink}`
// 👉🏻 format: <http://localhost:3000/facetime/><call.id>

Therefore, we need to create the /facetime/<callID> route to enable users to join a call. To do this, create a facetime folder with an [id] directory inside, and within that directory, add a page.tsx file. Then, copy the following code snippet into the file:

"use client";
import { useGetCallById } from "@/app/hooks/useGetCallById";
import { useUser } from "@clerk/nextjs";
import {
    StreamCall,
    StreamTheme,
    PaginatedGridLayout,
    CallControls,
} from "@stream-io/video-react-sdk";
import { useParams, useRouter } from "next/navigation";
import { useEffect, useState } from "react";

export default function FaceTimePage() {
    const { id } = useParams<{ id: string }>();
    const [confirmJoin, setConfirmJoin] = useState<boolean>(false);
    const [camMicEnabled, setCamMicEnabled] = useState<boolean>(false);
    const router = useRouter();
    //👇🏻 gets call details by ID
    const { call, isCallLoading } = useGetCallById(id);

    useEffect(() => {
        if (camMicEnabled) {
            call?.camera.enable();
            call?.microphone.enable();
        } else {
            call?.camera.disable();
            call?.microphone.disable();
        }
    }, [call, camMicEnabled]);

    //👇🏻 enable users to join calls
    const handleJoin = () => {
        call?.join();
        setConfirmJoin(true);
    };

    if (isCallLoading) return <p>Loading...</p>;

    if (!call) return <p>Call not found</p>;

    return (
        <main className='min-h-screen w-full items-center justify-center'>
            <StreamCall call={call}>
                <StreamTheme>
                    {confirmJoin ? (
                        <MeetingRoom />
                    ) : (
                        <div className='flex flex-col items-center justify-center gap-5'>
                            <h1 className='text-3xl font-bold'>Join Call</h1>
                            <p className='text-lg'>
                                Are you sure you want to join this call?
                            </p>
                            <div className='flex gap-5'>
                                <button
                                    onClick={handleJoin}
                                    className='px-4 py-3 bg-green-600 text-green-50'
                                >
                                    Join
                                </button>
                                <button
                                    onClick={() => router.push("/")}
                                    className='px-4 py-3 bg-red-600 text-red-50'
                                >
                                    Cancel
                                </button>
                            </div>
                        </div>
                    )}
                </StreamTheme>
            </StreamCall>
        </main>
    );
}

When users visit the meeting page, they are presented with a confirmation message, allowing them to confirm that they want to join the call.

In the code snippet above:

• The useGetCallById hook is a custom function that retrieves call details based on the call ID.

• The handleJoin function allows users to join the call and then displays the <MeetingRoom /> component.

Add the MeetingRoom component below the FaceTimePage component:

const MeetingRoom = () => {
    const router = useRouter();

    const handleLeave = () => {
        confirm("Are you sure you want to leave the call?") && router.push("/");
    };

    return (
        <section className='relative min-h-screen w-full overflow-hidden pt-4'>
            <div className='relative flex size-full items-center justify-center'>
                <div className='flex size-full max-w-[1000px] items-center'>
                    <PaginatedGridLayout />
                </div>
                <div className='fixed bottom-0 flex w-full items-center justify-center gap-5'>
                    <CallControls onLeave={handleLeave} />
                </div>
            </div>
        </section>
    );
};

The PaginatedGridLayout arranges participants in a grid layout with pagination, allowing you to manage larger video calls by displaying a set number of participants per page.

The CallControls component provides built-in actions, such as muting, video toggling, and screen sharing, that can be performed during a call. Both components are part of the Stream SDK, making integration seamless.

Additionally, you can switch to the SpeakerLayout, which highlights the dominant speaker or shared screen while displaying other participants in a smaller view.

Finally, create a hooks folder containing the useGetCallById.ts file and copy the code snippet below into the file:

import { useEffect, useState } from "react";
import { Call, useStreamVideoClient } from "@stream-io/video-react-sdk";

export const useGetCallById = (id: string | string[]) => {
    const [call, setCall] = useState<Call>();
    const [isCallLoading, setIsCallLoading] = useState(true);

    const client = useStreamVideoClient();

    useEffect(() => {
        if (!client) return;

        const loadCall = async () => {
            try {
                const { calls } = await client.queryCalls({
                    filter_conditions: { id },
                });

                if (calls.length > 0) setCall(calls[0]);

                setIsCallLoading(false);
            } catch (error) {
                console.error(error);
                setIsCallLoading(false);
            }
        };

        loadCall();
    }, [client, id]);

    return { call, isCallLoading };
};

The code snippet above filters the call list and returns the call with a matching ID, allowing users to join the specified call.

Retrieving Upcoming Calls

To retrieve upcoming calls from Stream, you can create a custom hook that fetches all the calls created by the user, as well as the calls they are a member of.

import { useEffect, useState } from "react";
import { useUser } from "@clerk/nextjs";
import { Call, useStreamVideoClient } from "@stream-io/video-react-sdk";

export const useGetCalls = () => {
    const { user } = useUser();
    const client = useStreamVideoClient();
    const [calls, setCalls] = useState<Call[]>();
    const [isLoading, setIsLoading] = useState(false);

    useEffect(() => {
        const loadCalls = async () => {
            if (!client || !user?.id) return;
            setIsLoading(true);
            try {
                //👇🏻 gets all the calls the user is featured in
                const { calls } = await client.queryCalls({
                    sort: [{ field: "starts_at", direction: -1 }],
                    filter_conditions: {
                        starts_at: { $exists: true },
                        $or: [
                            { created_by_user_id: user.id },
                            { members: { $in: [user.id] } },
                        ],
                    },
                });

                setCalls(calls);
            } catch (error) {
                console.error(error);
            } finally {
                setIsLoading(false);
            }
        };

        loadCalls();
    }, [client, user?.id]);

    const now = new Date();

    //👇🏻 gets only calls that are yet to start
    const upcomingCalls = calls?.filter(({ state: { startsAt } }: Call) => {
        return startsAt && new Date(startsAt) > now;
    });

    return { upcomingCalls, isLoading };
};

The useGetCalls hook retrieves the list of upcoming calls, which can then be displayed in the UpcomingMeeting modal.

Congratulations! You’ve completed the project for this tutorial.

Check out the live app here.

Next Steps

So far, you’ve learned how to build a video conferencing app. If you'd like to learn more about how you can leverage Stream to build scalable apps, then check out these resources:

• How to integrate Stream Chat Messaging

• How to integrate Stream Audio and Video calls

• How integrate Stream Activity Feeds

Before We End...

I hope you found it insightful and that it has given you enough motivation on how to build apps using awesome developer tools.

These are some of my other most recent blog posts.

• State of Databases for Serverless in 2024

• Neon Postgres vs Supabase

• MongoDB vs. PostgreSQL

Check out my blog for more tutorials like this on awesome developer tools.

Follow me on Twitter to stay updated on my side projects and ongoing learning.

Happy coding.

In this article, I'm going to break down all of the major ways you can use to create a React app and which one you should pick based off of your project's needs.

I'll also include a quick guide at the end to show you exactly how to choose between each according to the type of project you're building.

Let's get started!

❌ Why You Shouldn't Use Create React App

In 2023, the Create React App tool was deprecated, which means that it was no longer being maintained. Create React App has been the go-to way to make a new React project, but it's been dethroned by a number of different alternatives.

For that reason, Create React App is not an option I would recommend for creating a new React project in 2024.

💨 How to Create a React App with Vite

You may be asking, "What's a good replacement for Create React App?" That option is Vite.

Vite is ideal for making client-rendered React projects that run exclusively in the browser.

Vite docs home page

To spin up a new React project with Vite, you just have to run a single command:

npm create vite@latest my-react-app -- --template react

The great thing about Vite is, as its name indicates, it's much faster than virtually every alternative. Where Vite really shines is how quickly it runs in development.

Vite is unopinionated, however, which means you will likely need to install a suite of third-party libraries for basic functionality, like routing and data fetching.

If your application doesn't have a server or you are using an external API and it doesn't need server-side rendering, Vite is a perfect choice.

Additionally, Vite comes with its own config file, vite.config.js, which might require reading the documentation in order to configure things such as environment variables, build options, and image options.

🥞 How to Create a React App with Next.js

If you're looking for a way to build a React app that gives you a single-page app (SPA) experience but with server-side rendering and server components, Next.js is your choice.

Next.js docs home page

Next.js is the only option at the moment that comes with server components, which allows you to mark a component as async and await in some operation on the server.

async function getData() {
  const res = await fetch('https://api.example.com/...');
  return res.json();
}

export default async function Page() {
  const data = await getData();

  return <main>{data}</main>;
}

The benefit of server components is that you don't have to show a loading spinner in your app before fetching data. Server components allow you to ship far less JavaScript to the client, which leads to faster load times for your users.

Server components do require that you have a server, however, this means that it can't be deployed as simply as a client-rendered React app made with Vite.

Next.js is powerful because it comes with a ton of built-in features, such as a dedicated file-based routing, image optimization, and font loading, to name a few.

Next.js also allows you to tap into server actions, which is a new React feature that allows you to run server code by calling a function.

// Server Component
export default function Page() {
  // Server Action
  async function create() {
    'use server'

    // ...
  }

  return (
    // ...
  )
}

Next.js also has route handlers, which lets you to make HTTP requests to an API endpoint. This is something that client-rendered React apps can't do, because there's no server.

With all of Next.js' benefits, it comes with a steeper learning curve. There are a number of Next.js-specific concepts that may seem to go against some React concepts you've already learned.

For example, within server components, you can't use React Hooks. This means that you have to rely on patterns such as storing state in the URL.

Despite the learning curve, Next.js is the most popular React framework and is relied upon to build impressive React apps that power small startups to Fortune 500 companies.

If you want to make something impressive with React, you can certainly do it with Next.js.

💿 How to Create a React App with Remix

Remix, like Next.js, is a React-based framework that has a different focus on web standards to deliver a better user experience. Remix allows you to also write server and client React code.

Remix docs home page

Remix prides itself on serving static and dynamic content faster than Next.js. This means it's equally good at building full-stack applications as well as static websites.

Instead of server components and server actions, Remix simply has actions. Actions allows you to handle data mutations on your server, which is anything that isn't a GET request. Actions are just simple functions with the name action.

To get data, you use simple functions called loaders. React Remix uses React Router under the hood. So if you're comfortable with React Router, you'll likely feel at home with Remix as well.

export async function loader() {
  return json(await fakeGetTodos());
}

export default function Todos() {
  const data = useLoaderData<typeof loader>();
  return (
    <div>
      <TodoList todos={data} />
      <Form method="post">
        <input type="text" name="title" />
        <button type="submit">Create Todo</button>
      </Form>
    </div>
  );
}

Remix is a bit more stable than Next.js and has a less steep learning curve, still allowing you to build just as impressive applications, with the only downside being that it's not nearly as popular as Next.js. So it doesn't have the same community support and libraries around it.

But if you do want something with server-side rendering and client-side rendering, Remix still remains a great option to build your next React project.

🚀 How to Create a React App with Astro

The newest way to build a React project is definitely the most performant. React apps can also be built using a framework called Astro.

Astro docs home page

Astro's goal is deliver content to users quickly through something called "island architecture".

In short, this means that JavaScript is loaded only when the user needs them, making for a much more optimal user experience. If you want the fastest website possible, I'd highly recommend looking at Astro.

Astro supports server-side rendering and is great for SEO-focused websites that are largely static. However, what's neat about Astro is that it can also run code on the server if you choose to. It's not as popular to build fully dynamic, full-stack applications with Astro, but it is possible to do so.

Astro is also very flexible as it's not even tied to React. You don't need to use React whatsoever to build an Astro app, and you can use React alongside other frameworks such as Vue and Svelte within the same app.

If you're building a website that has posts or content that uses markdown or MDX, Astro should be your top choice. It uses a feature called "collections" to describe all the data within your markdown files so that you know exactly what content is going to be rendered in your React components.

Astro is gaining rapidly in popularity, and it's probably the best choice out there if you are interested in making a static website that doesn't need a database or authentication, or a website that is largely static.

🤔 So What Should I Choose?

If you've read up to this point and you're still trying to figure out which framework would be best for you to build a React project in 2024, here's the rundown:

• If you're just starting out and learning the React basics but want to build a simple or medium-sized project, stick with Vite.
• If you want a full-stack framework with all the bells and whistles, like server components, and you don't mind spending time learning additional concepts, check out Next.js.
• If you've tried Next.js and find some of its concepts difficult to understand, but still want to build a full-stack React application, definitely look into Remix.
• Finally, if you have a static or content-driven website, and you don't really need a database or authentication, I would highly recommend using Astro.

🏆 Become a Professional React Developer

Looking for the ultimate resource to learn React from start to finish?

✨ Introducing: The React Bootcamp

The bootcamp features every resource to help you succeed with React:

• 🎬 200+ in-depth videos
• 🕹️ 100+ hands-on React challenges
• 🛠️ 5+ impressive portfolio projects
• 📄 10+ essential React cheat sheets
• 🥾 A complete Next.js bootcamp
• 🖼️ A complete series of animated videos

Click below to try the React Bootcamp for yourself.

Click to get started

React Dev Tools is an extension created by the React team. It enables developers to debug their code inside their Developer Tools.

Once you add the extension, you will get 2 new tabs in DevTools called Components and Profiler, respectively.

Components and Profiler tabs in Chrome Dev Tools

To use the full functionality of the extension, you need to be in development mode. This is because in production mode, the component names get changed to letters (as you can see in above screenshot) and you will not be able to profile your components.

How to Use the Components Tab

The Components tab allows you to debug your code in dev tools with various functionalities. Let's cover them one by one:

You can check the props/ state/ hooks of the component

Viewing Props and State

This tab will help you to look for a component and check its respective props/ state in your dev tools, without having to log them in the console separately.

You can edit the props/ state from dev tools

One of the amazing features is that you can edit the props/ state of your component in the browser itself. This helps you to reflect changes in real time without having to reload or refresh your webpage. Above is a sample video so you can see how it works.

You can search for a component

You can easily search for a component within your whole application by just typing out the name in the search bar provided. It will show you all related components with the keywords typed in. Then you can navigate between the matching results.

You can check the component's tree

Component's Hierarchy

While debugging, its important to note which parent components caused the child component to re-render. Checking this in your code is sometimes tedious. But the "rendered by" section makes it easier for you by showing all the parent components in a single place.

You can log a component's data in the console

Logging a component's data in the console

There are developers who like to work in console, and this feature allows you to log all of your component's data to console with just one click. It shows all relevant information regarding the component like props received, hooks present, which node is it in the DOM, and the file's location in your system.

You can check subcomponents

Just like checking parent components isn't always easy in your code, the same applies with checking child components.

To overcome this issue, you can double click on a component name, which will show you all the subcomponents present inside the target component in one go.

How to Use the Profiler Tab

This tab allows you to test the performance of your components and shows which components to focus on for improvements.

Profiler tab

As you can see above, I've marked a few things on the screenshot. Let's cover them one by one:

• A is the record button, which will help you record a profiling session.

• B is the refresh button, which will help you refresh the page for a session.

• C is the clear button, which will help you clear the profiling session's result.

• D is the commit chart, which will show you the list of commits during a session.

• E is the component list, which will show you the components rendered during a session.

• F is the flame chart button, which will show you the component list like E.

• G is the ranked chart button, which will show you the component list in a ranked manner.

Now let's dive into different functionalities present in this tab and how to check the performance of your web page:

How to Read the Commit Chart

The commit chart shows the list of commits during a session. If you can see in the above image, in section D, there are 3 bars. These denote 3 commits in a session. And each commit shows a side effect that caused the DOM to update.

As per the docs, "The colour and height of each bar corresponds to how long that commit took to render. (Taller, yellow bars took longer than shorter, blue bars.)"

You can even navigate between the bars and check each commit separately.

How to Read the Flame Chart

Flame chart shows the list of components rendered in a commit. If you can see in the above image, when you click on the section labeled F, all horizontal bars in the section E represent different components of the 1st commit.

As per the docs, "The colour of a bar indicates how long the component (and its children) took to render in the selected commit. Yellow components took more time, blue components took less time, and gray components did not render at all during a commit."

How to Check the Performance of Your Web Page

To check the performance of your web page, all you need to do is:

• Click on the record button.

• Use your web page so that the Profiler will be able to analyse the rendering of components.

• Click the record button again to finish recording.

Then you will see the flame chart, and you can analyse which components are taking more time to render.

Note that the flame chart also shows:

1. When exactly the component rendered.

2. And how long it took to render in a profiling session.

For example: In below image, the Home component was rendered at 1.5s of the profiling session and it took 27.7 ms to render.

Flame Chart

How to Read a Ranked Chart

When you click the Ranked chart icon as shown in section G of the image, you will get a chart view of the components. This view is in descending order, that is the component that took the most time to render will be at the top and the component which took the least time will be at the bottom.

You can see this in the below image:

Ranked Chart

Note: You can get more information about why your component rendered by just enabling the "Record why each component rendered while profiling." checkbox in settings of the "Profiler" tab. I've attached an image for reference below:

Render description

Conclusion

React Dev Tools is a great extension to have when you're working on your React applications. They can help you easily debug your code and find performance bottlenecks in your application.

Do try out these features next time in your React project.

Thanks for reading!

If you found this article useful, do share it with your friends and colleagues.

If you like to see similar tips and tricks in HTML, CSS, JavaScript and React, do Follow me on LinkedIn.

It’s an important part of Chrome Developer Tools that you can use to check the source code of any website.

But it doesn’t end there. You can take things further by changing the elements and styles that make up the website – that is, the HTML, CSS, and JavaScript code of the website. This is why a lot of developers use the Inspect tool for debugging purposes.

If you’re a beginner in web development, the Inspect tool is a useful feature you can take advantage of to learn about how websites are built, the fonts, icons, and plugins used, and even who made the website.

The good news is that you don’t need to be the developer of the website to use this powerful tool as it is available to users as well. You don’t even need to be a developer at all to use it.

In this article, you will learn how to open the Chrome Developer Tools so you can get access to the Inspect feature, and how to inspect specific elements on a website. I will also show you how you can manipulate the elements of a website by changing the texts and styles.

I'll be using freeCodeCamp.org to show you how things work with the Inspect tool.

How to Open the Chrome Developer Tools

To open the Chrome Developer Tools, click the vertical dots at the top-right corner of your browser:

Then hover over “More tools” and select “Developer tools”:

You will then get access to the tabs of the developer tools such as Elements (the HTML and CSS that makes up the website), Console with which you can run JavaScript, Sources, and many more.

You can drag these tabs around and place them wherever you want:

How Do I Open Inspect Element in Chrome with the Keyboard?

You can open the Inspect element tool on Linux by pressing CTRL + SHIFT + C or F12 on Windows.

If you are on Mac, press Command + SHIFT + C.

How to Inspect Specific Elements on a Website

To inspect any element you see on a website, whether it's text, a button, a video, or an image, right-click on the element and click “Inspect”.

In this case, I will right-click on the “Learn to code – for free” text on the freeCodeCamp.org landing page.

The source code will open and the element will be highlighted for you, like this:

You can see the text is an h1 element.

How to Manipulate the Elements of a Website with the Inspect Tool

You can change the text contents of a website with the Inspect tool.

As an example, I’m going to change the “Build projects” text on the freeCodeCamp.org landing page to “Build real-world projects”.

To do this, right-click on the element you would like to change and click “Inspect”. In this case, it's the “Build projects” text:

Double-click on the “Build projects” text:

Type in “Build real-world projects” and hit ENTER:

You can see the text has been changed to “Build real-world projects”.

How to Change Styles with the Inspect Tool

Let’s change the background of the “Get started (it’s free)” button to my favorite color – #2ecc71.

Right-click on the button and select “Inspect”:

Double-click on the value of the “background-image” property on the right, that is linear-gradient(#fecc4c,#ffac33).

Change the colors to #2ecc71,#2ecc72 and hit ENTER: You can see the background of the button has changed.

We have now made 2 changes on the freeCodeCamp.org landing page – we changed the “Build projects” text to “Build real-world projects” and we changed the background of the “Get Started (it’s free)” button:

Are the changes you make with the Inspect tool permanent?

No. Any change you make with the Inspect tool is not permanent. Once you reload the page, the changes are gone.

This is because the website has been deployed to a server. So when you make another request to that server by reloading the page, the content from the server is loaded by your browser.

So don't worry - you playing around in this way with the Inspect tool won't change a website permanently. It just helps you learn more about it and practice your coding :)

Conclusion

This article showed you how to get access to the Developer tools of Google Chrome, how to use its Inspect feature to view the source code of a website, and how to change the elements and styles of a website with it.

If you just started learning to code in HTML, CSS, and JavaScript, the Inspect feature of Chrome Dev tools is a powerful tool you can use to view the source code of any website so that you can learn about how they are built.

Thank you for reading.

And you might see a color scheme or font on a specific website that you want to incorporate into your blog or web app. But you'll need a browser extension to see the website's color scheme and other CSS features.

The CSS overview feature in Chrome Dev Tools lets you see these CSS properties.

In this post, we'll go over how to use the CSS overview feature in Chrome Developer Tools. We'll also learn how to use CSS overview to get the colors and other CSS properties you want to use in creating a web page.

Let's get started. 💃

What is the CSS overview panel?

The CSS overview panel is one of the newest features of Chrome Developer Tools. It serves as a preview tool that allows you to see the different CSS properties used in creating a web page.

It displays CSS properties such as:

• The colors used on a web page.
• The line height of each element used on a web page.
• The font-size of each element used on a web page
• The font-families of each element on a web page.
• The font weights of each element used on a web page.

What are Chrome Developer Tools?

Chrome Developer Tools is also known as Chrome Dev Tools.

Chrome Dev Tools are a suite of web developer tools that come pre-installed in the Chrome browser.

Check out this article to know more about Chrome developer tools.

Here are some of the advantages of using Chrome Dev Tools:

• It enables you to create better websites in a shorter amount of time.

• It enables you to make changes to your code, test it, and inspect it.

• Chrome Dev Tools give developers more control over their web applications and browsers.

• It enables you to assess the general performance of a website.

How to Access Chrome Developer Tools in Your Browser

You can access Chrome Developer tools in three different ways:

1. Chrome’s Menu:

2. Click on the three vertical dots located on the top right corner of your chrome browser. It will bring up a drop-down menu with more tools at the bottom of the screen.

3. Click on more tools.

4. Click on developer tools.

2. Inspect:

3. Right-click on the chrome browser.

4. Click on inspect.

3. Shortcuts:

4. For Windows - CTRL + Shift + I OR F12.

5. For Mac - CMD + Shift + I.

Once you click on the shortcut keys, the developer tools open.

When you press CTRL + Shift + I, it displays the last panel you opened by default. It shows the element, console, network, or performance panel, among other things.

CTRL + Shift + C opens the element panel first by default.

How to Use CSS Overview in Chrome Dev Tools

The steps below will walk you through how to use the CSS overview feature to get the CSS properties used on a web page.

Step 1 - Open Chrome Dev tools

We've already covered the various methods for accessing Chrome developer tools. You should be familiar with them now.

As a quick reminder, you can open Chrome dev tools by pressing Ctrl + Shift + I on Windows and Linux. Use CMD + Option + I on Mac.

Step 2 - Click on More tools

Click on the three vertical dots located on the top-right of Chrome dev tools.

Select "More Tools" from the drop-down menu.

You'll discover a variety of options when you click "More Tools." From the various options, select the CSS overview feature.

Step 3 - Click on Capture Overview

When you click on CSS Overview, you'll see a list of its functions.

Functions such as:

• Capture an overview of your page's CSS.

• Identify potential CSS improvements.

• Locate the affected elements in the element panel.

Click on the Capture Overview button.

A menu with five sections appears after clicking the Capture Overview button.

The five sections are:

• Overview summary
• Colors
• Font info
• Unused declarations
• Media queries

Let's go over each of the five sections one by one to see how they work.

CSS Overview Summary

The Overview summary contains a list of the CSS elements used in building the web page.

The Overview summary displays a summary of the CSS on your website, such as:

• The number of elements used on the web page.
• The different types of selectors used in creating the web page.
• The number of inline style elements used on the web page.
• The number of external stylesheets used on the web page.

An Illustration of the overview summary.

The example above shows the various CSS elements used to build the web page.

Colors

The color panel displays all the colors used in creating the web page. It has a palette of colors for the background, text, fill, and borders. It also highlights low-contrast texts issues on the web page.

An illustration of the color panel.

The image above shows you the different colors used in creating the web page.

The beauty of the Color panel is that each color is clickable. If you click on a particular color in the Color panel, a list of elements that use that color appears. When you click on each element, it takes you to the element panel for inspection.

I clicked on color #49FCD4 in the image above, and it brought up a list of elements with that color.

You can also hover over an element in the lists of elements displayed. When you move your cursor over the element, it highlights the element on the web page.

When I hover my mouse over the header element in the image above, it highlights the header on the web page.

Just a quick note: hovering refers to moving your cursor over anything. It means to place a cursor over text, an image, or other objects on the screen without clicking on them.

Font Info

The font info panel displays the typefaces used in the development of the website. It shows you the font-size, line-height, font-weight, and font families used in creating the website. If you click on the occurrences, you will see a list of the affected elements.

An illustration of the font info panel.

The above image shows you the different typefaces used in creating the web page.

Unused Declarations

You can find CSS styles that do not affect the web page by using unused declarations.

An illustration of the unused declaration panel.

The image above shows the number of unused declarations on the web page. The vertical alignment applied to the element that isn't inline or a table cell will not affect the page.

You can also click on the occurrences to see a list of elements affected, like the font info and color panel.

Media Queries

The media query panel displays a list of all the media queries used in creating the web page. You will be able to examine the various widths and screen resolutions used in creating the web page.

An illustration of the media query panel.

The above example displays the number of media queries used in creating the web page. It lists the screen resolutions used in order of occurrence, from highest to lowest. If you click on the occurrences, you will see a list of the affected elements.

Conclusion

When it comes to evaluating CSS attributes on a web page, the CSS overview tool comes in handy. It allows front-end developers and designers to inspect the CSS properties on a web page.

Thank you for reading 💙. If you would like to chat or have any questions, please feel free to contact me anytime on Twitter: @cessss_ and linkedIn: Success.

Also, follow my blog to read some of my other stuff @cesscode.

Happy coding! 💙

No-code tools let people across the world build different products and applications without writing code.

Before no-code tools, building simple websites or mobile applications took weeks or months and only experienced software developers could do it.

But that's not the case anymore. Now, you can spin up blogs, websites, and more using the right no-code tools. And even if you know how to code, these tools can help you become more productive.

There are tons of no-code tools available today. So, choosing the right ones can be tricky. This article aims to highlight some of the best no-code tools for developers to use in 2021.

Webflow

Webflow is a powerful, web-based design tool that gives you the superpower of designing, building, and launching responsive websites without writing a single line of code. Amazing right? I know!

Rather than sketching/designing your projects and then coding them into an actual product, you use a different approach with Webflow.

Websites built with Webflow are powered by Amazon Cloudfront, hosted on Fastly, and don't require external plugins.

With Webflow, you can:

• Create automatic site backups (versioning) and staging URLs.
• Move from prototype to mockup in minutes.
• You can design hundreds of pages at once.
• Design, build and launch with no stress at all.

Pricing 💵

Webflow has a free tier and four other paid tiers listed below:

• Basic: $12 a month (paid annually) or $15 a month (paid monthly)
• CMS: $16 a month (paid annually) or $20 a month (paid monthly)
• Business: $36 a month (paid annually) or $45 a month (paid monthly)
• Enterprise: You have to contact the sales team to get this information

BuildBox

Did you ever think it was possible to create exciting games without writing code? I am happy to let you know that it is!

Imagine if you are already busy with coding a game app, but a new client asked you to create a game for them. Instead of rejecting the offer, you can use BuildBox to make the game. It's a win-win situation if you ask me. 😉

Buildbox is the world's first software that truly allows anyone to create amazing games regardless of technical skill. Due to its unique user interface, making games becomes a fluid process that doesn't require any scripting, programming, or software design experience.

As a developer, you can use Buildbox to:

• Drag and drop to create unique and professional 3D games.
• Add smart assets into your game.
• Add action effects and logic to your games and more! 🚀

Pricing 💵

Buildbox has a free tier and two other paid tiers listed below:

• Plus: $9.99 a month or $89.99 per year
• Pro: $224.99 per year

Hashnode

As a developer, blogging lets you share your technical knowledge and experience with the developer community. And it also helps you reinforce your learning on every topic you write.

Hashnode enables developers to create a blog mapped to their custom domain for free. So you only have to focus on publishing articles on your blog while Hashnode takes care of the rest – customization, readership, visibility, web monetization, and so much more.

Over the years, I've seen many developers build blogs from scratch only because they wanted to map it to their personal domain and give it a peculiar look and feel. Well guess what? This no-code tool lets you achieve all that and more.

With Hashnode, you:

• Don't have to worry about maintaining or constantly updating your blog since Hashnode handles everything.
• Only have to focus on writing and publish articles on the blog.
• Will get readership on your blog from day zero.
• Can customize your blog to meet your needs and so much more!

Pricing 💵

Hashnode is free forever for developers. However, they plan to launch a paid team tier for business.

Bubble

Bubble lets you create interactive, multi-user apps for desktop and mobile web browsers, including all the features you need to build a site like Facebook or Airbnb.

Traditional web applications require you to manage your code and set up a deployment process to a web server. Not Bubble – it handles your deployment and hosting for you.

Most importantly, there are no hard limits on the number of users, the volume of traffic, or data storage.

Here a couple of ways you can use Bubble as a developer:

• You can create mobile-friendly layouts and dynamic content for a polished product that you'll be proud to show off to your prospects, customers, or investors.
• You can build responsive web apps.
• You can create hybrid mobile apps.
• You can connect to external services and hardware through APIs.

Pricing 💵

Bubble has a free tier and three more paid tiers. Find the paid tiers below:

• Personal: $25 a month (paid annually) or $29 a month (paid monthly)
• Professional: $115 a month (paid annually) or $129 a month (paid monthly)
• Production: $475 a month (paid annually) or $529 a month (paid monthly)

Coda

Coda is an all-in-one doc that brings all of your words and data into one flexible surface.

With Coda, you no longer have an unconnected web of documents, spreadsheets, databases, and niche workflow apps to get things done – because everything will be unified and brought into one location.

Coda comes with building blocks like tables and buttons – and time-saving templates so your documentation can grow and evolve with the needs of your team.

Here are a few ways you can use Coda as a developer:

• You can manage data from somewhere else in a precise way for that specific instance.
• You can edit, contextualize, or "massage" data very quickly.
• You can show or hide rows or columns, drag-and-drop columns, even group by elements to create a pivot table or kanban board.

Pricing 💵

Coda has a free tier and three more paid tiers highlighted below:

• Pro: $10/month per doc maker (paid annually) or $12 a month (paid monthly)
• Team: $30/month per doc maker (paid annually) or $36 a month (paid monthly)
• Enterprise: You have to contact the sales team to get this information

Gumroad

Gumroad lets developers start selling their digital products in seconds. It also gives you access to a great list of tools to help you engage with an audience that cares about you and your work.

You can personalize your landing page to your heart’s content, embed a follow form, add a fantastic checkout and consumption experience, and gain access to robust data based on the usage of your product.

With Gumroad, you can:

• Be as powerful as the world’s largest retailers by setting up automatic workflows and up-sells.
• Keep your audience close by adding Gumroad's widgets directly on your website.
• Make money selling courses or e-books about tech, career growth, and more!

Pricing 💵

Gumroad makes money when the creator makes money. So, the platform is free until you have more than 1000 customers. Then, you will start paying $10 monthly or $108 per year.

Notion

Notion is a fantastic tool that helps you organize your work, and you can pretty much adjust it to fit all of your needs. Also, there are a lot of templates to choose from made by incredibly creative people.

Here a couple of ways you can use Notion as a developer:

• To publish and advertise your schedule or a schedule of an upcoming event you are organizing.
• You can use it for note-taking.
• It helps you collaborate with others.
• You can use it to compile and share public documents and more.

Pricing 💵

Coda has a free tier and three more paid tiers highlighted below:

• Personal Pro: $4 a month (paid annually) or $5 a month (paid monthly)
• Team: $8 a month (paid annually) or $10 a month (paid monthly)
• Enteprise: You have to contact the sales team to get this information

Voiceflow

Voiceflow provides you with the resources you need to design, prototype, and launch voice and chatbots without writing any lines of code.

Its fast and visual drag-n-drop canvas allows you to leverage components, robust context models, interaction model exports, and more.

This no-code tool is a game-changer when it comes to creating voice or chatbots. You should check it out.

With Voiceflow, you can:

• Design prototypes for Alexa and Google Assistant.
• Build voice apps as good as custom code, easier and faster.
• Track and analyze the results of your voice apps with custom analytics.
• You get context first designs that enable you to create engaging contextually layered voice apps and conversations effortlessly.

Pricing 💵

Voiceflow has a free tier and two more paid tiers highlighted below.

• Pro: $40 a month (paid annually) or $50 a month (paid monthly)
• Enterprise: You have to contact the sales team to get this information

Bumpa

Bumpa is that one stop shop for everything a developer or business owner needs to sell online and manage their business. With Bumpa, you can set up your website with your products in less than 5 minutes.

Bumpa allows you to record sales from your website, your physical shop, various marketplaces and even on social media. This no-code tool stands out because of the ease of setting up and also managing both your online and offline systems.

With Bumpa, you can:

• Create an online store.
• Manage orders and products, track sales, share across Facebook, Instagram and Twitter.
• Accept payment and send out notifications to your customers directly through the app.

Pricing 💵

Bumpa has a free plan for all its users. But if you need more features, you'll have to use upgrade to a premium plan which is $9 monthly.

Zapier

You can do a lot of the work you do every day automatically thanks to Zapier.

It helps you connect your apps and moves information between them automatically. This lets you focus on your most important work instead of doing repetitive tasks.

Zapier gives you more time to build relationships, grow your team, test new strategies, and do work you enjoy. 😃

Here a couple of ways you can use Zapier as a developer:

• Receive emails for new jobs from your favourite job board.
• Auto-reply to Slack messages and mentions.
• Turn emails into Trello task cards.
• Streamline your recruitment process.

Pricing 💵

Zapier has a free tier and four other paid tiers highlighted below.

• Started: $19.99 a month (paid annually) or $29.99 a month (paid monthly)
• Professional: $49 a month (paid annually) or $73.50 a month (paid monthly)
• Team: $299 a month (paid annually) or $448.50 a month (paid monthly)
• Company: $599 a month (paid annually) or $898.50 a month (paid monthly)

Shopify

Want to start an e-commerce business? You should check out Shopify.

Why, you may ask?

The truth is, Shopify helps you bring your business online by enabling you to create e-commerce websites backed by powerful tools that help you find customers, drive sales, and manage your day-to-day.

I like Shopify because it doesn't restrict you to selling only online products like most platforms. You can sell everywhere – in person with Point of Sale and online through your website, social media, and online marketplaces.

Here a couple of ways you can use Shopify as a developer:

• Create an e-commerce website for your clients or employer
• Learn about Shopify and become a Shopify developer (They get paid a good amount of money).
• Sell e-books, T-shirts, and more for people in the developer community.

Pricing 💵

• Basic Shopify: $29 monthly
• Shopify: $79 monthly
• Advanced Shopify: $299 monthly

Cardd

Whether it's a personal profile, a landing page to capture emails, or something a bit more elaborate, Cardd has you covered.

Guess what? You can publish these sites to any custom domains you own with full SSL support.

With Cardd, you can:

• Create a simple, free, fully responsive one-page site for pretty much anything.
• Build and publish more than three sites from a single Carrd account.
• Embed your custom widgets from third-party services.

Pricing 💵

Carrd has a free tier and three other paid tiers listed below:

• Pro Lite: $9 annually
• Pro Standard: $19 annually
• Pro Plus: $49 annually

Airtable

Airtable is a cloud collaboration service with the features of a database and a spreadsheet formatted in a way that lets you always know what’s going on.

The fields in an Airtable table are similar to cells in a spreadsheet but have types such as checkbox, phone number, drop-down list, images, and more.

Users can create a database, set up column types, add records, collaborate, sort records, and even publish views to external websites.

Whether you need to organize a calendar of project deliverables, compile a customer list, or organize any other type of information, Airtable makes it easy to create and collaborate.

Here a couple of ways you can use Airtable as a developer:

• Airtable lets you build spreadsheets. So, you can leverage each spreadsheet as a database.
• Create views designed for different use cases.
• Connect your workflow to hundreds of apps and services, or access your content programmatically.

Pricing 💵

Airtable has a free tier and three other paid tiers shared below:

• Plus: $10 a month (paid annually) or $24 a month (paid monthly)
• Pro: $20 a month (paid annually) or $50 a month (paid monthly)
• Enterprise: You have to contact the sales team to get this information

IFTTT

With IFTTT, you can connect your apps and devices in new and remarkable ways you didn't think were possible. It enables you to build a more connected world that works for you.

One integration with their API protocol connects your product to hundreds of apps, devices, and brands. They also have a fantastic documentation for developers. You should check it out.

Here a couple of ways you can use IFTTT as a developer:

• You’ll be able to gain insights into how people connect and use your products so you can further personalize their experiences.
• Build and publish applets for others to use.
• Find brands that complement yours.

Pricing 💵

IFTTT has a free tier and four more paid tiers highlighted below:

• Pro: $3.99 monthly
• Developer: $199 annually
• Team: You have to contact the sales team to get this information
• Enterprise: You have to contact the sales team to get this information

Conclusion

In an age where the demand for software far exceeds the supply of coders, no-code development tools are helping people design and build products and websites quickly.

The best time to jump on to the no-code train is now. No-code is the future. If you become an expert now, you will be one of the most in-demand people in the future. - Arun Saigal, Cofounder and CEO Thunkable.

The quote above summarises my thoughts about no-code tools and why you should start using them now.

That's all, folks! I hope this was helpful. If yes, follow me on Twitter to access more content like this.

So how can we use Postman to both test our existing APIs and understand how they work?

• What is Postman?
• What are we going to build / learn?
• Part 0: Getting set up with Postman
• Part 1: An introduction to Postman
• Part 2: Creating a new Postman request to GET info about Squirtle
• Part 3: Creating a collection of requests in Postman for the PokéAPI
• Part 4: Making POST requests with Postman to translate sentences to sound like Yoda
• Part 5: Authenticating requests to the Lord of the Rings API with an API Key

What is Postman?

Postman is a tool teams can use to reliably test APIs using easy to use configurations. It comes stocked with features you would expect when dealing with APIs, including authentication, setting headers, customizing the payload, and a bunch more that help reduce the friction of using an API.

And it’s not just for testing. The beauty is that this can be used for many aspects of working with APIs for many different members of the team. Maybe a Project Manager wants to verify that things work or might find it easier to make a change straight with the API, or a QA Engineer needs to make sure everything still works, or a developer wants to actively make changes while working on the API itself.

The best part about it – Postman provides collaboration features. The free tier includes exporting and importing collections of saved API requests as well as creating shared links. If you're part of a team, they have paid tiers that allow you to sync up your collections to make sure everyone has the most recent and up to date collection.

What are we going to build / learn?

We’re going to walk through two different example APIs to cover the concepts of Postman.

First, we’ll walk through some simple HTTP requests with a public API for Pokémon.

We’ll then use the Yoda Translator API for one part to demonstrate how to make specific HTTP requests.

Once we understand how the basics work, we’ll use the Lord of the Rings API to learn how authentication works with APIs. For this, you’ll need to register for a free account for an API key.

Part 0: Getting set up with Postman

Before we get started, you’ll need Postman in order to follow along with this walkthrough. The good news, is Postman is available for free on Mac, Windows, and Linux, so you should be able to find a version that works for you.

Get Postman: https://www.postman.com/downloads/

Once downloaded, go through the standard installation instructions, open it up, and we should be ready to go!

Part 1: An introduction to Postman

The first time you open up Postman you’ll immediately be shown a launchpad with a bunch of options to get started.

It might seem a bit overwhelming, but let’s break down some of the key concepts that we’ll need to know.

Requests

A request is kind of what it sounds like, it’s a specific API request. This will be a single type of request, whether it’s a GET or POST to a specific endpoint. You’ll want to create new requests for each type of endpoint which will allow you to move between them when testing.

Collections

A collection is a group of requests. This is handy for organizing your requests into different groups. This could be as simple as two totally different APIs (ie. Twitter vs Slack) or it could be two different groups of APIs for a single API (ie. Twitter Tweets API vs Twitter Accounts API).

Authorization

Authorization is how requests are authenticated with an API, whether by a person making a request or by a computer making that request on your behalf. This commonly comes in the form of an API key which can be a static value assigned to your account or dynamically generated with tools like OAuth.

Environments

Environments will allow you to configure your endpoints to use specific variables that make it easier to use the same endpoints between different environments. For instance, you might have the same /profile endpoint on both your production and development environments, but they have different domains. Environments lets you manage a single request with a variable domain.

Workspaces

We won’t go too far into workspaces in this post, but it allows you to manage and organize different sets of collections. Imagine if you want to use Postman for both work and a personal project, you might have a Work workspace as well as a Personal workspace.

For the purposes of this article, we’ll be covering Requests, Collections, and Authorization.

Part 2: Creating a new Postman request to GET info about Squirtle

Now that we have a better understanding of the different terminology, let’s actually create a request.

At the top left of the UI you should see a but orange button that says New. Go ahead and click that and then select Request.

Before we get into the request itself, it requests a few things.

This first thing requires is a name. We’re going to start off by requesting information about the Pokémon Squirtle, so let’s name this “Pokémon - Squirtle”.

It also requires a collection, so click Create Collection and let’s name the collection “My Favorite Pokémon”.

Click the orange checkmark button next to the collection name then hit Save.

At this point we’ll have a new request, so let’s build that request.

There are two things we’ll first need to fill out for our first request:

• Request type: GET, POST, PUT, etc - we’ll use GET
• Request URL: The endpoint for your API request - for our request we’ll use https://pokeapi.co/api/v2/pokemon/squirtle/

And once you make sure those are correct, you can simply hit the blue Send button on the right and we’ve successfully made our first request!

We immediately get a few things we can see:

• Body: at the bottom we should now see the response body of the API request. For our Squirtle API, we should have a JSON object with data like abilities, base_experience, and forms.
• Status: on the right, we should see the HTTP status code. “200 Ok” is a good sign and it means it was successful!
• Time: simply how long the request took to finish
• Size: the size in KB (in our example) of the response data

You can also hover over Status, Time, and Size and get a more in depth look at each option.

So we made our first request!

Once thing to notice before we move on is that our request looks like it’s in a browser tab. If we’re done with that particular request, we can close the tab and click Save to make sure all of our changes are there for next time!

Part 3: Creating a collection of requests in Postman for the PokéAPI

Now that we’ve created a request, let’s create a collection of them. Technically we already had to create a new collection for Part 2, but we’ll create a new one to learn how collections themselves work.

At the top left of the UI, click the orange New button again and select Collection.

Similar to a request, it asks for a name so let’s call this “PokéAPI”. Optionally you can add a description, then click Create at the bottom.

On the left, you’ll now see your collection. You can select and expand the folder since we’ll be working with it.

Before we add a request, the PokéAPI has different types of requests, so it makes sense to organize it a little more thoroughly. So let’s click the three dots next to the PokéAPI collection and select Add Folder.

Similar to the others, this asks for a name. Folders are kind of like collections inside of a collection, so you get similar options. Let’s name this one “Pokémon” and click the orange Save button like before.

Now let’s add our requests! First, click the three dots next to the Pokémon folder, similar to how we added a folder to the collection, but this time select Add Request.

Let’s name this request “Pokemon”. While it might be confusing that we have a Pokemon request inside of the Pokémon folder, Pokemon is just one of the endpoints of the Pokémon group.

Now, let’s use the same exact API that we used with our Squirtle request before:

• Request Type: GET
• Request URL: https://pokeapi.co/api/v2/pokemon/squirtle/

And similar to before, when we hit the blue Send button, we should see a successful request!

Now let’s add another request. Follow the same process as before to create a new request under the PokéAPI Pokémon folder and let’s name this request “Abilities”.

If you scroll through the response from the first Squirtle endpoint, you see a lot of other API urls. At the top, we have abilities and we have two different ones — “torrent” and “rain-dish”.

Choose your favorite Squirtle ability and copy the url value into the new Abilities request we just created, I’m going to use rain-dish.

We can leave the Request Type as GET, hit the blue Send button, and we can again see a successful response!

Here we get a lot of information about our Squirtle ability Rain Dish and some of the details come in different languages which is cool!

So now we have a new PokéAPI collection with a Pokémon folder representing the group of Pokémon API endpoints including Pokemon and abilities.

We’re going to stop Part 3 with those 2 requests, but feel free to continue on and add as many of the PokéAPI requests as you’d like!

Part 4: Making POST requests with Postman to translate sentences to sound like Yoda

So far we’ve only made GET requests, but what if we wanted to make a POST request where we need to actually send some data?

For making a POST request, we’re going to use the Yoda Translator API from funtranslations.com. While this API only takes a single parameter, it’s still a good public endpoint we can use to understand the concept.

First, let’s create a new collection with a new request:

• Collection: Fun Translations
• Request: Yoda

This time, instead of a GET request, our request configuration will be:

• Request Type: POST
• Request URL: https://api.funtranslations.com/translate/yoda

Now this time, if we hit the blue Send button, we’ll notice we don’t get a successful 200 response, we get a 400!

We never actually set up any data to be posted to the API and it requires that data, so let’s add it.

Right below the Request URL, click Body. Then instead of none, select raw as the body type. Finally, on the far right of the types, change Text to JSON.

Then, in the space below it, you can add the following:

{
    "text": "Hello, I am learning how to test APIs with Postman!"
}

And now click the blue Send button again and we get a successful response!

We can apply this concept to pretty much any API. Postman doesn’t only permit you to post JSON, it allows you to use the other formats that we see listed in the Body Type section, meaning you have a lot of options depending on what the API you’re using requires.

Part 5: Authenticating requests to the Lord of the Rings API with an API Key

For the rest of the walkthrough, we’re going to use the Lord of the Rings API.

First up, the Lord of the Rings API requires authentication in order to make requests using an API key. So to start, you’ll before we dive in, you’ll need to go create a free account.

https://the-one-api.herokuapp.com/sign-up

Once you sign up and log in, the first thing you’ll see is your API key! Either copy this key down or remember where you can find it for later. If you leave the page, you can always grab it by navigating to Welcome and then Account in the navigation of the API website.

To get started, let’s first create a new collection and request:

• Collection: Lord of the Rings
• Folder: Movie
• Request: All Movies
• Request Type: GET
• Request URL: https://the-one-api.herokuapp.com/v1/movie

Once you’re set with the above, click Send, and you’ll notice immediately it gives a response that says 401 and that it’s unauthenticated.

Because this API requires the API key, this is exactly what we expected. So let’s click on the Authorization tab. We can then select a Type of Bearer Token, and on the right, we can paste in our key that we just set up with the Lord of the Rings API.

And as soon as we hit Send, we now see a successful response!

This worked really great, but what if we have a bunch of requests that use a single key. Do we have to manage that on each request?

Instead of managing it on each individual request, we can manage it on the collection. Let’s first build another request.

Under our Lord of the Rings collection and in the Movie folder, create a new request:

• Request: Quote by Movie ID
• Request Type: GET
• Request URL: https://the-one-api.herokuapp.com/v1/movie/{id}

In this request, let’s use an ID from the response of the first request, I’m going to use 5cd95395de30eff6ebccde5b which is the ID of The Two Towers, so the request URL will look like:

https://the-one-api.herokuapp.com/v1/movie/5cd95395de30eff6ebccde5b

Now, instead of setting our token in the request Authorization, we’re going to leave the type as Inherit auth from parent. Click on the three dots next to the collection and select Edit.

Here, we’re going to do the same exact thing we did with the first request but on the Collection configuration. Select the Authorization tab, under type select Bearer Token, and in the Token field again paste your token.

Finally, click Update and hit the blue Send button again and we can see a successful request!

We can now go back to our All Movies request and update the Authorization to use a Type of Inherit auth from parent and it should still continue to work!

What else can we do with Postman?

While I covered a lot of the basics, there’s quite a lot more you can do with Postman. Here are a few of my favorites.

Environment Variables

If you’re working as a developer on a project, it’s likely that your team uses multiple environments, such as a development and production environment. Instead of creating and maintaining completely separate requests, you can add an environment variable and instead change that variable when switching between environments!

Variables apply to many scenarios, but that’s a common use. Check out Postman’s docs to learn how.

https://learning.postman.com/docs/postman/variables-and-environments/variables/

Import and Export Collections and Data

A great thing about Postman is once you have your requests all organized, you can export them for others to use. This also means that you can import collections from other team members. This makes it much easier to make sure everyone’s using the same collection.

Bonus: you can even store these files in a Git repository, as they’re just JSON.

But keep in mind - if you’re using Authorization on the collection like we went over in this guide, you’ll want to make sure you don’t include that when exporting your collection.

https://learning.postman.com/docs/postman/collections/importing-and-exporting-data/

Automated testing

Once you have a set of requests in a collection and even better, if you’re storing them in Github, you can begin to use those requests as part of a way to manage automated testing of your API.

While there are a few solutions for doing this, Postman includes a Collection runner built right into the app and Newman is a command line tool that lets you run tests right from the terminal.

https://www.postman.com/use-cases/api-testing-automation/

What’s your favorite way to test and play with APIs?

Share with me on Twitter!