Forem: Xu Bian

How Codex Can Drive Verifiable SketchUp Modeling

Xu Bian — Wed, 06 May 2026 00:22:11 +0000

This is not a step-by-step tutorial.

Until the demo path is fully verified, I do not want to package it as something readers can simply follow and reproduce. A more accurate label is architecture walkthrough: this piece explains why Codex or another agent CLI should not "magically control SketchUp" directly, and why it should instead use verifiable intermediate layers to turn natural-language intent into checkable, executable, repairable project state.

Using SketchUp Agent Harness as the example, Claude and Codex are only entry points. The important structure sits in the middle:

agent CLI
-> runtime skills
-> MCP server
-> structured design model
-> SketchUp Ruby bridge
-> SketchUp scene

This chain determines whether the agent is generating a one-off result or maintaining a design project.

Why Codex Should Not Directly Operate SketchUp

The most obvious idea is to let Codex understand the user's request and directly call SketchUp.

That idea is tempting, but it creates several problems.

First, software operations can become a black box. What Codex did, why it did it, which objects were created, and where dimensions came from become hard to trace without structured records.

Second, design state gets scattered. Some of it sits in chat, some in the SketchUp scene, some in temporary scripts, and some in the user's head. When the project continues later, the agent may not know the real current state.

Third, mistakes are hard to repair. If the result looks wrong, the agent may patch the current scene instead of going back to source evidence and the structured model to fix the root cause.

Codex should not simply become SketchUp's hand. It should be an agent entry point that understands intent, calls tools, checks results, and drives repair.

The stable execution capability should live in the tool layer and the project state layer.

Layer 1: Agent CLI Understands Intent

The user begins with natural-language intent.

For example:

"Create a 2 m by 1.8 m bathroom with a toilet, vanity, door, mirror, basic lighting, and a clearance check."

Codex's value is not to turn that sentence directly into a one-off script. Its value is to understand the design actions inside the request:

create a space
set dimensions and units
place components
apply basic rules
check clearances
generate an execution plan
push the result into SketchUp

Codex is the entry point and coordinator. It is not the source of truth.

Layer 2: Runtime Skills Provide Design Context

Natural-language understanding is not enough.

A general agent may know what a bathroom is, but it may not know how this product represents spaces, how components are registered, how design rules work, when layout validation is required, or when a project-specific repair must not become a global rule.

That is the role of runtime skills.

In a system like SketchUp Agent Harness, runtime skills should serve design tasks, not product maintainers. They can tell the agent:

how to create or open a design project
how to handle space planning
how to import a floor plan
how to search and place components
how to apply design rules
how to record visual feedback
how to turn feedback into structured repair

These skills should not mix in release workflow, test workflow, or maintainer-only development rules. At runtime, designers need design task capability, not product engineering context.

Layer 3: The MCP Server Defines the Tool Boundary

If Codex is the entry point and runtime skills provide task context, the MCP server is the stable tool boundary.

It should handle things like:

reading project state
updating the structured model
running validation
generating execution plans
exposing clear tool interfaces
turning agent requests into controlled product operations

This layer matters because it turns model-session intent into auditable tool calls.

Without it, an agent may directly generate scripts, edit files, or operate software. That may feel flexible in the short term, but it is hard to maintain.

With it, Codex can change, Claude can change, and future agent CLIs can change, while the project protocol and execution model remain stable.

Layer 4: The Structured Model Holds Project Truth

The core of SketchUp Agent Harness is not a chat entry point. It is the structured design model.

In this project, design_model.json holds the working truth of the design project:

spaces
dimensions
components
rules
assumptions
source evidence
execution plans
repair clues

This layer determines whether the system is reliable.

Without a structured model, Codex may generate a SketchUp scene that looks correct, but it will be difficult to continue reliably next time.

With a structured model, the system can support:

diff
validation
replay
repair
version comparison
source-backed correction

The SketchUp scene is the execution result. design_model.json is the project state that the agent can keep understanding.

Layer 5: The Ruby Bridge Executes Into SketchUp

Design still needs to enter SketchUp.

The Ruby bridge's role is to send structured operations into SketchUp, rather than forcing the agent to carry all software details inside the conversation.

This layer should be stable, diagnosable, and allowed to fail clearly.

A good bridge does more than create objects. It should report when SketchUp is not in the right state, when the bridge is missing, when execution is blocked by software state, or when the returned structure is not what the upper layers expected.

Structured errors matter. They keep the agent from guessing and prevent it from mistaking a software-state problem for a design problem.

Layer 6: Visual Review Returns to Structured Repair

After execution in SketchUp, review is still necessary.

Screenshots, top views, and renders can reveal many problems: wall misalignment, reversed orientation, missing openings, incorrect component scale, or material and lighting mismatches.

But visual review should not stop at "this image looks wrong."

If a designer accepts a visual correction, the system should turn it into structured repair:

update the model diff
correct source evidence
add validation rules
record component or material changes
save project-local memory
execute or replay again

That is the loop.

Codex should not only generate the first version. It should help find problems, explain them, call tools, and repair them.

What the Full Chain Looks Like

At an abstract level, one natural-language modeling request can be decomposed like this:

1. The user expresses design intent.
2. Codex uses runtime skills to classify the task.
3. The MCP server reads or creates project state.
4. The structured model records spaces, rules, components, and assumptions.
5. Validators check dimensions, clearances, or structural issues.
6. The execution plan becomes SketchUp bridge operations.
7. The Ruby bridge executes inside SketchUp.
8. A screenshot or view becomes a review artifact.
9. Designer feedback is written back into the structured model.
10. The system validates, repairs, or replays.

This is more complex than "type one sentence and generate a model."

But it solves the reliability problem: the project can continue, mistakes can be located, designer feedback can be traced, and the model can be replayed.

Why This Is Not Codex-Specific

Codex is not the only core of this architecture.

Claude, Codex, and future agent CLIs can all be entry points. The parts that should remain stable are:

runtime skills
MCP tool layer
design model schema
SketchUp bridge
protocol documents
validation loop

This means the agent entry point can change without rewriting project state and execution boundaries.

It also avoids hard-coding the habits of one model product into the core system. Claude-specific and Codex-specific logic should stay in adapters as much as possible, not inside the MCP server or the structured model.

What Should Not Be Overclaimed Yet

The boundary matters.

SketchUp Agent Harness is still an early-stage open-source project. It should not be packaged as a mature commercial design platform.

What is ready to discuss is the architecture direction and the product boundary that already exists: natural-language entry, MCP server, Ruby bridge, structured model, runtime skills, protocol, and validation loop.

To turn this into a true tutorial, we still need a verified public-safe demo path: public-safe input, a full run from natural-language goal to SketchUp execution, review, and repair.

Until then, this article explains the architecture. It does not promise that readers can reproduce a full demo by following steps.

Conclusion

Codex-driven SketchUp modeling is not about letting Codex directly control software.

The key is the middle layer.

Natural language is only the entry point. The SketchUp scene is only the execution result. What makes the system sustainable is the combination of runtime skills, MCP server, structured design model, Ruby bridge, and visual review loop.

Without these layers, AI modeling easily becomes one-off output.

With these layers, an agent can move from "help me draw something" toward "help me maintain a design project."

Originally published on my personal site:
https://marlinbian-site.pages.dev/writing/codex-driven-sketchup-modeling/

More links: GitHub · YouTube · LinkedIn · Bluesky · Mastodon · Discord

Designers Should Think, Not Draft

Xu Bian — Wed, 06 May 2026 00:22:01 +0000

When AI enters design tools, the most common misunderstanding is that designers can finally "draw with one sentence."

That is attractive. Fewer manual steps, fewer menu clicks, and less repeated operation are real improvements.

But if an AI design tool only moves designers from manually operating software to verbally operating software, it is not enough. The designer has only moved from being a mouse-and-shortcut operator to being a prompt-and-chat operator.

The more valuable direction is not to make designers faster drafting operators. It is to help designers spend more of their energy on ideas, judgment, constraints, and tradeoffs.

Drafting Is Not Low-Value, But It Is Not All of Design

To be clear: drafting is not low-value work.

Drawings, models, sketches, and renders are design language. Without expression, design judgment cannot be communicated or checked.

The problem is that real design work often spends too much time on repeated execution rather than judgment:

placing the same type of component in the right position
adjusting dimensions and clearances according to rules
filling in walls, openings, and furniture from existing boundaries
moving back and forth between several versions
turning verbal feedback into model changes
repeatedly checking whether drawings, models, and screenshots still match

These tasks require patience and precision, but they do not all need to be executed line by line by the designer.

The irreplaceable part of design is deciding what is worth doing, why it should be done that way, which constraints cannot be broken, where compromise is acceptable, and whether the final expression still matches the intent.

AI design tools should serve that judgment instead of producing more output that the designer has to inspect and repair.

"One-Sentence Design" Can Hide the Real Problem

If a tool's main promise is "type one sentence and generate a space," it can hide complexity very quickly.

A generated bathroom, living room, or exhibition booth may look plausible. That does not mean the design workflow is working.

The designer still needs to know:

whether the dimensions are credible
where the walls and openings came from
whether components have semantics and dimensions
whether clearances have been checked
whether visual feedback can return to the model
whether the AI can still understand the current state next time

If those questions have no answer, AI has only compressed execution into a result. It makes the first generation faster, but it does not make ongoing design more stable.

That is why AI design tools should not optimize only for prompt-to-image or prompt-to-scene. They need to organize design work as a continuing workflow.

What a Better Workflow Looks Like

In my view of SketchUp Agent Harness, an AI tool for designers should at least support this chain:

design intent
-> project directory
-> structured working model
-> design rules
-> components and source evidence
-> SketchUp execution
-> visual review
-> structured repair

The key point is that the designer is not dealing with a black-box output. The designer is maintaining a project.

A designer can express a goal in natural language:

"Create a 2 m by 1.8 m bathroom with a toilet, vanity, door, mirror, basic lighting, and a clearance check."

But the agent should not only turn that sentence into a picture. It should turn the request into project state: space dimensions, components, rules, assumptions, clearance checks, an execution plan, and a repairable model.

Next time, the designer should not need to start over. They should continue from an existing project state.

Designers Should Control Judgment, Not Every Execution Detail

AI can take on more low-level execution, but it should not take away design judgment.

A better division of labor is:

AI organizes project state
AI executes repeated modeling actions
AI turns source evidence into a first working model
AI checks structural problems
AI turns visual feedback into repairable actions
designers decide direction, constraints, tradeoffs, and acceptance criteria

This does not make designers less involved. It moves their involvement to the level where it matters more.

If designers still have to confirm every line, every object, and every small position, AI has only added a new interface.

If a designer can say "this opening should not be sealed," "this wall is too thick," or "this area is not a room, it is an exterior void," and the agent can write that feedback back into the structured model, then AI is starting to support real design work.

Runtime Skills Should Serve Design Tasks

This is why I treat runtime skills as an important part of design tools.

A designer-facing skill should not be a maintainer's development note. It should not expose internal product implementation details.

It should serve real design tasks, such as:

space planning
floor plan import
component search
design rules
semantic placement
visual feedback
structured repair

The role of these skills is not to give the AI a few prompting tricks. Their role is to help the agent know how to act in a specific design context, how to respect project state, and how to avoid turning a local project decision into a global product rule.

Runtime skills are part of the design workflow, not marketing packaging.

Local Project Memory Must Not Pollute Product Rules

AI design tools also face a practical problem: every design project has local facts.

The orientation of one floor plan, a client's preference, a scale correction for one import, or a room naming convention may belong only to the current project.

If the agent writes those local facts into product defaults, the product will quickly become unstable.

A better approach is layered:

product runtime skills hold general design task capability
project or session memory serves only the current project
maintainer development skills serve product development and release work
only generalized and validated patterns move into central knowledge or product rules

This layering is not engineering neatness for its own sake. It protects the designer's work boundary and the privacy of client materials.

AI Should Reduce Noise, Not Create More Drafts

A weak AI design tool generates endless options and leaves selection, repair, explanation, and finishing work to the designer.

A better AI design tool should reduce noise.

It should help designers reach a state they can judge, not produce a pile of results that cannot continue.

For designers, the valuable outcome is not "AI gave me many images." The valuable outcome is:

I can understand why the current proposal looks this way
I can point out a problem
AI can turn the problem into a structured change
I can keep versions
I can keep moving instead of restarting

That is workflow-level efficiency.

Conclusion

I do not think AI makes designers less important.

If the tool is designed well, AI can release designers from a large amount of low-level execution and help them focus on intent, judgment, constraints, review, and tradeoffs.

But the tool itself has to respect design workflow.

It cannot only pursue "type one sentence and generate a result." It has to maintain project state, preserve source evidence, execute into professional software, accept visual feedback, and write that feedback back into structured truth.

Designers should not become drafting operators in the AI era.

Designers should become directors of the design workflow.

Originally published on my personal site:
https://marlinbian-site.pages.dev/writing/designers-should-think-not-draft/

More links: GitHub · YouTube · LinkedIn · Bluesky · Mastodon · Discord

Why AI Design Tools Need a Source of Truth

Xu Bian — Wed, 06 May 2026 00:21:04 +0000

The most impressive moment in many AI design tools is simple: you type a sentence, and the tool gives you an image, a model, or a space that looks almost finished.

But once you move from a demo into a real design workflow, the hard questions appear quickly.

Can this result keep being edited?

Where did the walls, doors, objects, and dimensions come from?

When a designer points out a problem, did the AI repair the structure, or did it only patch the visible output?

When the project is opened again, how does the agent know what was design intent, what was a temporary experiment, what came from a source drawing, and what was only an assumption?

This is why I think AI design tools should not optimize only for "it looks generated." They need an editable, verifiable, repairable, replayable source of truth.

By "source of truth," I do not mean that AI should decide what good design is. I mean a structured working fact layer where intent, evidence, spaces, dimensions, components, rules, assumptions, and execution results have a place to live, can be checked, and can be repaired when they are wrong.

Output Alone Is Not Enough

If AI only generates an image, the result is easy to understand visually, but it is a weak long-term working base.

An image can express style, mood, and direction. It is much less reliable at carrying:

wall thickness
door and window openings
space boundaries
component dimensions
clearance rules
drawing evidence
design assumptions
change history

The same problem appears when AI only manipulates a SketchUp scene. The SketchUp scene matters, but it does not automatically tell the agent why an object is there, which dimension came from a designer instruction, which one came from an imported drawing, and which change was only a temporary exploration.

Chat history is not enough either. Conversation is good for expressing intent and discussing judgment, but it is a poor long-term structured state for a design project.

A reliable AI design tool therefore cannot have only a final image or a final scene. It needs to know what the current project actually is.

A Source of Truth Makes the Project Continue-able

In SketchUp Agent Harness, design_model.json is the structured working truth for a design project.

It is not an aesthetic judgment. It is not a legal compliance report or a construction document. It is closer to a shared project state between the designer and the agent.

It should record things like:

how spaces are organized
what the dimensions and units are
which components are already in the project
what semantics, anchors, and clearances those components have
which design rules are currently active
which conclusions came from an imported drawing, image, or scan
which parts are assumptions
which visual feedback needs to become a structured change

With that layer, an agent can do important work:

compare versions
check whether the structure is reasonable
repair a model using source evidence
replay the structure into SketchUp
turn visual feedback into precise model changes

That is the value of a source of truth. It does not make the output more spectacular. It makes the project understandable, checkable, and repairable.

The SketchUp Scene Is Not the Source of Truth

This can be misunderstood.

The SketchUp scene is important. Designers need to see, inspect, adjust, and often deliver work through SketchUp.

But for an agent, the SketchUp scene is better understood as a live execution result. It is the result of execution, not the whole project truth.

There are three reasons.

First, a software scene contains a lot of implicit state. It is hard for an agent to know the evidence, assumption, or design intent behind every object.

Second, a scene can mix several rounds of experiments. Without structured records, it is hard to tell what should remain and what was only leftover exploration.

Third, repair can easily become patching the current picture. That may improve the short-term appearance while making the long-term project harder to trace.

A stronger loop looks like this:

design intent
-> structured truth
-> SketchUp execution
-> visual review
-> structured repair

In other words, the SketchUp scene and screenshots should feed back into structured truth.

Visual Feedback Must Return to Structure

Visual review matters.

A top view can expose wall misalignment, missing openings, reversed orientation, or an exterior void that was mistaken for a room. A render can expose material, lighting, scale, or style problems.

But visual feedback should not stop at "this image looks wrong."

If a designer says:

"This wall is too thick."

Or:

"This opening should not be sealed."

Or:

"This area is not a room. It is an exterior void."

A good agent should not only tweak the current view. It should turn that feedback into structured actions:

update wall thickness
correct space boundaries
update opening evidence
add a validation failure
record uncertainty in the source interpretation
create a replayable model diff

The next time the project is opened, the agent should not merely remember that the user disliked an image. It should know how the project truth changed.

Floor Plan Import Especially Needs a Source of Truth

Floor plan import is a useful example.

If a user gives AI a DWG, DXF, PDF, image, scan, or photo, the weakest workflow is to generate a model that looks plausible and then treat it as fact.

A more reliable workflow should:

Register the source.
Preserve source evidence.
Interpret scale, orientation, boundaries, rooms, walls, and openings.
Generate a first editable working model.
Execute or preview it in SketchUp.
Use a top view, screenshot, or validator to find problems.
Write repairs back into structured truth.

The first import result should not be treated as a verified survey. It is working truth.

That distinction matters.

AI does not need to be perfect on the first pass. It needs to admit what came from evidence, what was inferred, what is uncertain, and let the designer repair errors in natural language.

What This Means for Designers

If an AI design tool has a structured source of truth, the designer's role becomes clearer.

Designers do not need to manually execute every low-level modeling step, and they should not need to restate the same project context in chat again and again.

They should spend more attention on higher-value work:

judging whether a space makes sense
confirming design intent
choosing style and material direction
managing constraints and tradeoffs
reviewing visual output
deciding which feedback should enter project truth

AI should not turn designers into drafting operators who happen to use natural language. A better direction is to let designers become directors and reviewers of the workflow.

What This Means for AI Products

For AI products, a source of truth changes the architecture.

If a product only optimizes for output, it can focus on prompts, image generation, and one-off results.

If it wants to enter real workflows, it has to handle more structure:

project directories
structured models
source evidence
runtime skills
design rules
component metadata
software bridges
validators
versioning and replay
visual review loops

SketchUp Agent Harness is interesting not because it is already a mature platform, but because it exposes this problem clearly.

Claude and Codex are only entry points. The more important layer is the combination of an MCP server, a SketchUp Ruby bridge, runtime skills, protocol documents, and design_model.json.

That middle layer decides whether the agent is generating a result or maintaining a project.

A Source of Truth Is Not a Universal Answer

The boundary also needs to be clear.

design_model.json is not aesthetic judgment.

It cannot decide whether a space is beautiful.

It is not a construction compliance report and should not be treated as legal, code, or engineering review.

It is a structured working fact layer. It carries current project state, sources, assumptions, rules, and repairable structure.

The real design judgment still belongs to the designer.

This is why "source of truth" should not mean "the only correct answer." In this context, it means "the single traceable working state."

Conclusion

When I evaluate whether an AI design tool has really entered a workflow, I look for answers to a few questions:

Where is the current model's structured state?
What evidence supports each important conclusion?
Do the visual output and structured model agree?
What concrete change does designer feedback become?
Can the project be checked, repaired, and replayed?

If those questions have no answer, the AI is still mostly an output engine.

If those questions have answers, the AI is starting to become a real design workflow tool.

That is why AI design tools need a source of truth.

Originally published on my personal site:
https://marlinbian-site.pages.dev/writing/why-ai-design-tools-need-a-source-of-truth/

More links: GitHub · YouTube · LinkedIn · Bluesky · Mastodon · Discord

SketchUp Agent Harness

Xu Bian — Wed, 06 May 2026 00:20:54 +0000

SketchUp Agent Harness is an early-stage open-source project for connecting design agents such as Claude Code and Codex CLI to SketchUp. The goal is to let designers express intent in natural language and turn that intent into verifiable, executable, repairable project state.

Project repository:

github.com/marlinBian/sketchup-agent-harness

It is not a plugin for only one AI tool. Claude and Codex are entry points. The more stable core is the MCP server, SketchUp Ruby bridge, structured design model, component metadata, runtime skills, and protocol documentation.

What Problem This Project Tries to Solve

Many AI design tools stop at "generate an image from a prompt" or "operate a few software steps for me." That can be useful for inspiration, but it is not enough for real design work.

Designers need a workflow that can keep going:

design intent can be recorded
floor plans, images, scans, and other source material can be preserved
model state can be checked and repaired
software execution can be traced back to structured facts
visual feedback can become explicit changes instead of being buried in chat history

The core judgment behind SketchUp Agent Harness is that AI design tools need a structured source of truth. In this project, the key file is design_model.json. SketchUp scenes, screenshots, and renders matter, but they are better understood as execution results or review artifacts. They should not be the only long-term truth of the project.

What It Can Do Today

Based on the current project documentation, the 1.0 version is still early, but it already has several foundational capabilities:

initialize an isolated design project directory
install the SketchUp Ruby bridge
install Claude and Codex runtime skills into the project
generate simple spaces and bathroom layouts through natural language
import DWG, DXF, PDF, image, scan, or photo inputs into a first editable model
store structured design truth in design_model.json
preserve source evidence, screenshots, versions, and project rules

The intended workflow is not that designers clone the source repository for normal design work. A more typical path is:

Install the harness package.
Install or update the SketchUp Ruby bridge.
Create a clean design project directory.
Run Claude or Codex in that design project directory.
Describe the design goal in natural language.

Why the Source of Truth Matters

If AI only generates an image, designers have limited ability to keep editing, checking, replaying, or repairing it.

If AI only operates a SketchUp scene directly, many design decisions become hidden inside software state. A later agent may not know what was design intent, what was a temporary action, what came from the original drawing, and what was only inferred.

A structured model makes these things explicit:

spaces
dimensions
components
rules
assumptions
source evidence
execution plans
review and repair clues

That is what lets the agent support diff, validation, repair, and replay. It also lets designers focus more on intent, judgment, constraints, and tradeoffs instead of repeatedly becoming drafting operators in the AI era.

Architecture

One way to understand SketchUp Agent Harness is as a chain from natural language to SketchUp execution:

designer intent
-> agent CLI
-> runtime skills
-> MCP server
-> structured design model
-> SketchUp Ruby bridge
-> SketchUp scene
-> visual review
-> structured repair

The important part is not any single agent model. The important part is the verifiable protocol layer and the structured project state in the middle.

That is why the project includes:

MCP server
SketchUp Ruby bridge
runtime skills
protocol specs
spatial behavior specs
project workspace docs
import pipeline docs
visual review loop docs

Current Limits

This project should not be described as a mature commercial design platform.

A more accurate description is: an early-stage open-source harness for exploring how natural-language agents can control SketchUp reliably and organize the design process into a checkable structured workflow.

Floor plan import is especially important to frame correctly. The first generated model should be treated as an editable working model, not a survey-grade result. Real component libraries, more complex collision checks, more stable drawing recognition, and fuller design rules still need continued iteration.

What I Plan to Write Next

This project is also the starting point for a set of essays and demos.

The first thread is source of truth:

Why AI design tools should not only pursue "it looks generated," and why they need editable, repairable, replayable structured truth.

The second thread is the designer workflow:

Designers should spend more energy on ideas, judgment, constraints, and tradeoffs instead of manually executing every low-level modeling step.

The third thread is implementation:

How Codex or Claude can use runtime skills, an MCP server, a SketchUp bridge, and design_model.json to turn natural language into verifiable SketchUp project state.

I also plan to produce demo videos based on this project, using a public-safe example to show the full path from natural-language goal to SketchUp model, review, and repair.

Originally published on my personal site:
https://marlinbian-site.pages.dev/projects/sketchup-agent-harness/

More links: GitHub · YouTube · LinkedIn · Bluesky · Mastodon · Discord

A Personal AI Workbench for Ordinary People

Xu Bian — Tue, 05 May 2026 00:50:54 +0000

I finished an English series on the way I think ordinary people can start using AI for real work.

The point is not to become an AI expert first.

The point is to have one place where you can say what you want, give the tool access to the right folder, and check the result.

Anything important still needs a human pause: publishing, deleting, paying, or authorizing.

My preferred starting point is simple:

One project folder. One command-line window. One plain-English request. One habit of checking before confirming.

That is the "AI workbench" idea.

Why I started with the command line

Most people hear "command line" and think it means programming.

I think that is the wrong frame.

For an AI tool like Codex, the command line can be the cleanest interface because it does not start with a pile of buttons.

You type the goal:

I want to organize the files in this folder and turn the useful material into a public article.

Please inspect the folder first.
Tell me what looks public, what looks private, and what you would do next.
Do not move or publish anything until I approve the plan.

This is not a developer-only request. It is a normal human request with a goal, boundary, and confirmation rule.

What the series covers

The series is for people who can use a computer or phone, but do not want to memorize AI jargon before doing anything useful.

It covers:

The practical test

My test for an AI tool is not whether it has the most impressive demo.

It is whether it can reach the work.

The questions I ask are practical:

Can it read the current folder?
Can it edit the file I am actually working on?
Can it run a check?
Can it open or name the next page I need?
Can it stop at the moment where I need to confirm an account, payment, deletion, authorization, or public publish?

If a tool cannot reach the work, it may still be useful for conversation. But it is not a workbench yet.

The safety boundary

This series is not an argument for handing judgment to AI.

The more useful an AI tool becomes, the more important the boundary becomes.

I do not want AI to decide medical, legal, investment, payment, publishing, or deletion questions for me.

What I want is preparation, inspection, comparison, drafting, organization, and explanation — then a stop where a human decision is needed.

That habit matters more than any specific product name.

A first prompt

If you already have Codex installed, start in an empty folder and try this:

I want to start using AI to help me get things done, but I am not a programmer
and I do not want to learn a bunch of jargon first.

Please tell me: in this folder, what can you help me with?
Can I ask you to read files, change content, make a plan, explain something, or check for errors?
Give me one small first task I can do here — steps small enough that you can guide me through each one.

The question is not "how much AI theory do I know?"

The better question is: can I describe a real task clearly enough that the tool can help me move one step?

Full series:

https://marlinbian-site.pages.dev/en/tutorials/ai-workbench-for-everyone/

Originally published on my personal site:
https://marlinbian-site.pages.dev/en/tutorials/ai-workbench-for-everyone/

More links: GitHub · YouTube · LinkedIn · Bluesky · Mastodon · Discord

Your first personal website with Codex, without fearing the tools

Xu Bian — Mon, 04 May 2026 05:14:34 +0000

I finished a seven-part beginner series on building a personal website with Codex.

The reader I had in mind is not a programmer.

They can use a computer, copy text, open a browser, sign in with Google when needed, and read a page to see whether it says the right thing.

That is enough for a first site.

The mistake I wanted to avoid was making people learn the whole map before they can move.

A normal person should not need to understand GitHub, Cloudflare, DNS, build output, or deployment pipelines before the first useful action.

My rule for the series is simple:

The reader should be able to act before they fully understand the system.

What the series covers

The route starts with one clean folder, not a platform dashboard.

There is also a series entry point:

Your first personal website with Codex, without fearing the tools

The first prompt matters

The series does not begin with:

Build me a personal website.

That is too vague. Codex has to guess the audience, scope, privacy boundary, and first structure.

The better first move is closer to this:

I want to build my first personal website, but I am not a programmer.

Please break the process into small steps I can follow.
Do not make me understand GitHub, Cloudflare, DNS, or build commands first.

For now, inspect the current folder and tell me whether it is safe to start here.
If it is safe, give me the smallest first plan.
If it is not safe, tell me which empty folder I should use instead.

Version one only needs:
- home page
- about page
- work or writing list
- contact page

Please keep warning me about anything that should not be public.

Now Codex has a real job: guide the route, keep the scope small, and protect the boundary.

Deployment should not start with manual upload

One part I rewrote after trying the flow myself: the publishing step should not ask a beginner to upload dist or build by hand.

The path I prefer is:

ask Codex to inspect the project;
let Codex prepare Git and the deployment path;
let Codex open or name the page where the reader must sign in, choose an account, authorize, or confirm;
use the free public URL first;
buy a custom domain only after the free version works.

The reader should not have to know which website comes next before Codex tells them.

Maintenance is the real test

The first launch is not the end. A personal site only matters if the owner can keep changing it.

That means every update should be small:

change one sentence;
add one article;
replace one image;
preview locally;
run checks;
publish through the workflow this project actually uses.

If something breaks, the fix should start from the symptom, not from rebuilding the whole site.

Privacy is not optional

A personal website is public. Search engines may index it. Someone may forward it. Years later, you may forget what was once there.

So the last step is a pre-publish check:

page text;
screenshots and images;
filenames and links;
API keys or environment files;
placeholder text;
broken links;
phone readability.

This is not about making the site empty. It is about keeping the public boundary clean.

Why I wrote it this way

Most beginner tutorials still assume the reader already has a map in their head.

This one assumes the opposite.

A reader can say what they want, confirm account pages, authorize tools, and check the result.

Codex should handle the mechanical parts and explain the next page only when it appears.

That is a more honest beginner workflow than pretending everyone wants to become a web developer before they can have a small home on the web.

Full series:

https://marlinbian-site.pages.dev/en/tutorials/first-personal-site-with-codex/

Originally published on my personal site:
https://marlinbian-site.pages.dev/en/tutorials/first-personal-site-with-codex/

More links: GitHub · YouTube · LinkedIn · Bluesky · Mastodon · Discord

How much does a personal independent site really cost?

Xu Bian — Sun, 03 May 2026 23:13:20 +0000

The Short Version

A personal independent site can start at $0/year.

If you do not buy a top-level domain, you can publish the first version on a free provider subdomain from Cloudflare Pages, Netlify, Vercel, or GitHub Pages. An address like your-name.pages.dev is already enough for learning, drafts, a small portfolio, or a family project.

That does not mean a site stays free forever. Costs usually appear when:

You want a domain that belongs to you.
You use paid tools such as Codex, ChatGPT, design software, or image generation to move faster.
Your site grows into heavy media, email, databases, login, comments, search, or commercial features.

So the real question is not “can I hack together the cheapest possible site?” The better question is: where does a normal person actually spend money when building a serious personal site?

Separate Three Kinds Of Cost

When people ask what a website costs, they often mix three different bills.

Infrastructure cost keeps the site online: domain, DNS, static hosting, storage, CDN, and certificates.

Tool cost helps you build faster: Codex, ChatGPT, design tools, image generation, writing tools, and code editors.

Maintenance cost keeps the site useful over time: new content, privacy review, backups, redesigns, renewals, and broken-link cleanup.

For a static personal site, the first category is often the cheapest one. The expensive part is attention, plus any tools you buy to save time.

Three Budget Routes

Route One: Start Free

Budget: $0/year

Best for:

Learning before you know whether you will keep publishing.
Giving projects, notes, or family material a temporary public address.
Accepting a provider subdomain.
Avoiding business email, backends, memberships, payments, and databases.

A free first version can look like this:

Item	Choice	Estimate
Domain	Use `.pages.dev`, `.netlify.app`, `*.vercel.app`, or GitHub Pages	$0
Static hosting	Cloudflare Pages, Netlify, Vercel, or GitHub Pages free tiers	$0
HTTPS	Automatic on the platform	$0
Content	Markdown, MDX, and ordinary image files	$0
Email	Keep using Gmail or public social profiles	$0
Analytics	Cloudflare Web Analytics or GA	$0

The tradeoff is ownership of the address. If you move providers later, the old provider subdomain may stop being the stable entrance to your work.

For version one, that is fine. If you do not yet know whether you can keep the site alive for a month, not buying a domain is a reasonable decision.

Route Two: Own The Address

Budget: about $10-20/year for basic infrastructure

Best for:

Treating the site as a long-term public identity.
Putting the URL on a resume, portfolio, social profile, or business card.
Wanting readers and search engines to remember your domain instead of a platform subdomain.

This route usually adds only one paid item: a domain.

Item	Choice	Estimate
Domain	Buy a `.com`, `.net`, `.dev`, or similar top-level domain	Often about $10-20/year, depending on TLD and registrar
DNS	Cloudflare DNS or registrar DNS	$0
Static hosting	Cloudflare Pages, GitHub Pages, Netlify, or Vercel free tier	$0
HTTPS	Automatic on the platform	$0
Inbound email	Cloudflare Email Routing into Gmail	$0
Outbound email	Start with Gmail, upgrade later if needed	$0+

As of May 3, 2026, Porkbun's domain pricing page shows .COM from $11.08, but domain prices vary by TLD, first-year promotion, and renewal. Always check the renewal price before buying. Cloudflare Registrar says it sells and renews domains at cost without markup, but you still pay registry and ICANN costs.

This is the route I would recommend for most serious first versions: buy the domain, keep hosting free, and keep the content as files you control.

Route Three: Add Tools And Growth

Budget: $20/month and up, depending on what you add

Best for:

People who already know they will publish regularly.
People who want AI tools to reduce the technical and writing burden.
Sites with large images, videos, downloads, or interactive features.
Sites that need professional email, collaboration, a CMS, database, search, comments, or automation.

At this point the cost is less about “the website” and more about the workbench around it.

Item	When it matters	Estimate
Codex / ChatGPT	You want AI help editing code, writing pages, running checks, and organizing content	ChatGPT Plus is listed at $20/month; Codex limits and rates depend on plan and usage
Object storage	Images, attachments, or downloads outgrow the repo	Cloudflare R2 has a free Standard storage allowance, then charges by storage and operations
Professional email	You need to send as `hello@yourdomain.com`	Free forwarding can start it; full sending usually needs a mail service
Paid hosting	You need higher build limits, teams, serverless functions, or commercial features	Free to monthly plans, depending on provider
Database / CMS	You need login, comments, memberships, forms, or non-technical editing	Can start free, then becomes usage-based
Paid analytics	You need privacy-focused analytics, team reports, or longer retention	Free to monthly plans

This is not the route for day one. Ship the site first, learn whether you will maintain it, then upgrade.

Is Codex A Website Cost?

Yes, but only if you count it correctly.

If you already pay for ChatGPT Plus, Pro, or a team plan, using Codex for your site may be a near-zero marginal cost. It is another use of a tool you already have.

If you subscribe to ChatGPT Plus only to build the site, then you can count it as a $20/month tool cost. It is not hosting, and it is not a domain bill. You are paying to save time, lower the technical barrier, and let an AI assistant inspect and edit the project.

OpenAI's help docs say Codex is included with ChatGPT Plus, Pro, Business, and Enterprise/Edu plans, while usage limits depend on the plan and task complexity. The Codex rate card moved toward token-based credit usage in April 2026, so “$20/month” should not be read as an unlimited Codex promise.

A more practical calculation:

If you only use AI to build version one:
Domain $10-20/year + AI tool $20/month, then cancel when done if you want.

If you use AI all year for writing, site edits, images, and content operations:
Domain $10-20/year + AI tool from $240/year.

Codex is an efficiency cost. It is not a required infrastructure cost.

Do You Need A Domain?

No.

Without a domain, you can use provider subdomains:

Cloudflare Pages: your-site.pages.dev
Netlify: your-site.netlify.app
Vercel: your-site.vercel.app
GitHub Pages: username.github.io

Those addresses open, share, and work. For learning, experiments, temporary portfolios, and family projects, they are enough.

The reason to buy a domain is not status. It is durability:

You want readers to remember one stable address.
You may change hosting providers later without changing public links.
You want to put the URL on a resume, portfolio, card, or long-term profile.
You want search engines to associate your name and work with your own address.
You want an address such as hello@yourdomain.com.

My rule for beginners: if you have not published three pieces or maintained the site for four weeks, wait before buying the domain. Prove the habit first.

Why Can Static Hosting Be Free?

Because static sites are cheap to serve.

A static site is mostly HTML, CSS, JavaScript, and image files. When someone opens a page, the platform sends files from a CDN. It does not need to run a custom server program for every request.

Cloudflare Pages advertises unlimited static requests. Its limits documentation lists 500 builds per month on the Free plan, 100 custom domains per project, and up to 20,000 files per Free-plan site. Netlify's pricing page lists a Free plan at $0 with 300 credits per month. Vercel documents the Hobby plan as free with automatic HTTPS, Git integrations, preview deployments, and 100 GB of Fast Data Transfer. GitHub Pages describes itself as static hosting for HTML, CSS, and JavaScript files from a repository.

That is why a first personal site should avoid unnecessary backend complexity. The closer it stays to static files, the cheaper and easier it is to move.

Will Images, Video, And Downloads Become Expensive?

Normal images usually will not.

A few compressed images in each article can live in the repository or static hosting. Costs become more likely when you publish:

Many full-resolution images.
Video files.
Large PDFs, software packages, audio, or downloads.
A frequently accessed asset library.

Then object storage may make sense. Cloudflare R2's pricing page lists a 10 GB-month monthly free allowance for Standard storage, then storage and operation charges after that, with no Internet egress bandwidth fees. That is generous for ordinary personal sites, but heavy reads can still create operation costs.

For version one, keep it simple: compress images, host video on YouTube, Bilibili, or another video platform, and embed or link from the site.

Do You Need Paid Email?

Not for version one.

You can start with Gmail, social links, or a simple contact page. After buying a domain, you can think about hello@yourdomain.com.

If you only need inbound mail, Cloudflare Email Routing says it can create custom addresses and route them to your preferred inbox, and it is free and private by design. That solves receiving and forwarding. It is not a full professional mailbox. Reliable sending from your domain usually needs Google Workspace, Fastmail, Zoho, iCloud Custom Email Domain, or another mail service.

For a personal site, solve “can people reach me?” before solving email branding.

When Do You Need A Backend, Database, Or CMS?

When the need is real.

Version one usually does not need a database. Articles, projects, and pages can be Markdown or MDX files.

Backend costs start to make sense when:

Users need to log in.
Readers can comment.
You have paid content or memberships.
Forms need a real admin workflow.
Non-technical collaborators need to edit content.
Search, recommendation, or personalization becomes complex.

All of that can be built later. None of it is required for a first independent site.

A More Realistic Budget Table

Scenario	First-year infrastructure	AI / tools	What it feels like
Learn and test	$0	$0+	You can start now
Free subdomain + one month of Codex	$0	about $20	Cheapest serious validation route
Domain + free static hosting	about $10-20	$0+	Best serious starting point
Domain + year-round ChatGPT Plus / Codex use	about $10-20	about $240/year+	Tool cost, not hosting cost
Growing personal site	about $10-20+	$20-50/month or more	Depends on email, storage, CMS, analytics, and backend

The most common mistake is to say “an AI-built site costs hundreds per year.” More precise: the site itself can cost about ten to twenty dollars per year; separately, you may buy an AI tool that helps with coding, writing, images, and operations.

My Recommendation

If you do not have a site yet:

Start on a free subdomain and publish version one.
Publish three pieces, or maintain the site for four weeks.
If the habit survives, buy a domain.
Upgrade storage, email, backend, or team features only when they block real work.
Judge Codex and similar AI tools by time saved, not by whether they are required.

The best thing about an independent site is that it does not require a large commitment on day one. Start at $0, prove that you want to keep writing and organizing your work, then spend money where the need is real.

References

Originally published on my personal site:
https://marlinbian-site.pages.dev/en/tutorials/personal-site-cost/

More links: GitHub · YouTube · LinkedIn · Bluesky · Mastodon · Discord

Build your own independent site with Codex

Xu Bian — Sun, 03 May 2026 12:37:44 +0000

The Short Version

You do not need to become a programmer before you can have your own place on the web. You need to make three decisions first:

What should last: artwork, essays, projects, learning notes, tutorials, or a family archive.
How often you will update it: weekly, monthly, or only when a real project is ready.
How much maintenance you can accept: no-code, light file editing, or a long-term code project.

Codex sits between light file editing and a long-term code project. It is not a magic website button. It is a local collaborator that can inspect a project, edit files, run checks, and explain the changes. The official OpenAI Codex CLI documentation describes it as a coding agent you can run locally from the terminal, working inside the selected directory.

That makes it useful for the repetitive parts: setting up folders, creating pages, adjusting styles, turning Markdown into pages, running builds, and checking that private material has not entered the public site.

A Website Is Not Just Another Feed

Social platforms are useful. They are where distribution, feedback, and discovery happen. But they are not good archives. Rules change, timelines bury work, and links can become fragile.

An independent site solves a different problem: it gives your public work a stable address.

A healthier publishing order looks like this:

Publish the complete version on your site first.
Then adapt it for Xiaohongshu, WeChat, YouTube, Bluesky, DEV.to, or other platforms.

This keeps the source version in your hands. You can still benefit from social platforms without letting them become the only copy of your work.

Choose By Person, Not By Tool

Designers And Artists

Start with a portfolio. Do not start with a complex blog system.

Your strongest assets are images, project process, taste, and judgment. A first version can be very small:

Home: one clear sentence about who you are, plus selected work.
Work pages: one page per project, with images, context, process, and outcome.
About: what you do, what kind of collaboration fits, and how to contact you.

For a designer, Codex should not decide which work is good. Its job is to make the structure steady: create pages, keep image sizing consistent, add alt text, update navigation, and run checks.

Engineers And STEM Builders

Start with project records and reusable notes.

It is easy to over-engineer your own site. The better first version is practical:

Project pages: what you built, why it exists, what stack you used, and what happened.
Tutorials: reusable explanations for things you keep teaching.
Playgrounds: small demos or tools people can try without an account.

If you are comfortable with Git, Markdown, Astro, and static hosting, Codex can be very effective. It can work inside the repository and run the build. Your job is to review the changes and keep the important decisions explicit.

Children And Family Projects

Start with safety, simplicity, and adult review.

A child's site should not begin with public attention. A better goal is a safe record:

A small wall of work: drawings, crafts, Scratch projects, or reading notes.
A learning log: one or two sentences each week.
A review flow: drafts stay local until an adult checks them.

Privacy matters more than polish. Do not publish school names, home locations, routine schedules, identity documents, or anything that makes the child easy to identify. Codex can help scan text, but an adult must make the final decision.

Writers, Teachers, And Small Service Businesses

Start with articles and useful resources.

Writers need durable long-form links. Teachers need organized materials. Small service businesses need a clear public introduction. A first version can be:

Home: what value you provide.
Writing or resources: public material grouped by topic.
Contact: one low-friction way to reach you.

You do not need a complex system at the beginning. Let the work have stable URLs first. Add newsletters, courses, payments, membership, or automation only when the content proves the need.

The Steady Route

If you do not know what to choose, I would start here:

Write content in Markdown or MDX.
Build the site with Astro.
Keep history in Git.
Deploy to Cloudflare Pages, GitHub Pages, Netlify, or Vercel.
Treat social platforms as distribution, not the archive.

This route is not the only good route. Its advantage is durability. Your content remains ordinary files. If you change themes, hosting providers, or domains, the articles and images are still yours.

No-code tools are also valid. Framer, Webflow, Carrd, Notion-style sites, and similar tools can be faster for a single polished homepage. The deciding question is simple: if you need one beautiful page, no-code may be faster. If you want years of essays, tutorials, projects, and interactive demos, a file-based site is usually steadier.

A Better First Prompt For Codex

This prompt is too vague:

Build me a personal website.

A better starting prompt is:

Please help me build a personal independent site in the current directory.
The audience is not programmers only. People should understand me through work and writing.
The first version needs a home page, about page, writing list, project list, and contact page.
Store content in Markdown or MDX. Public content should not depend on a database.
Inspect the project structure first, give me a short plan, and wait before editing files.

If you already have materials, add a privacy boundary:

The materials/inbox folder contains images and drafts.
First list what is suitable for public use and what may be private.
Do not move anything from private into public or src/content.

A good prompt does not lock every technical detail. It states the goal, audience, boundaries, and acceptance checks.

Keep Version One Small

The first version only needs five areas:

Home: one clear positioning sentence and recent work.
About: who you are and what you are focused on now.
Writing: articles and durable opinions.
Projects: work, experiments, and tools.
Contact: email, social links, and collaboration paths.

Avoid login, comments, CMS complexity, memberships, heavy animation, and multilingual admin systems at the beginning. Add them only after you have a real publishing rhythm.

Launch Checklist

Check at least these items before publishing:

Every page is readable on a phone.
The home page explains who you are within ten seconds.
Each article has a title, description, date, and tags.
Images have reasonable dimensions and alt text.
Secrets, private drafts, backend screenshots, and child-sensitive details are not in public folders.
The build command passes.
Important links open correctly.

This is where Codex helps: run the build, inspect diffs, and list risks. Still, read the public pages yourself before shipping.

References

Originally published on my personal site:
https://marlinbian-site.pages.dev/en/tutorials/build-personal-site-with-codex/

More links: GitHub · YouTube · LinkedIn · Bluesky · Mastodon · Discord