Hello. I’m Chieko Aihara, Product Manager on the KUSANAGI development team.
Recently, I have been using AI agents more often to write programs, research data, and draft articles.
However, preparing a development environment on each PC can be surprisingly time-consuming. Libraries and settings may differ from one PC to another, making it difficult to resume the same work immediately.
Another challenge was carrying over my conversations with AI. Code and documents can be shared through Git, but simply moving the files does not preserve what I discussed with the AI or why a particular decision was made. I created Markdown handoff files and passed them to the next session, but they could not carry over the entire conversation.
It was also inconvenient to stay close to my PC while a long-running task was in progress.
To reduce these inconveniences, I gradually refined my workflow using handoff files, tmux, and codex resume. Through that trial and error, I arrived at a setup in which a Linux server running KUSANAGI serves as the base for AI-assisted development, with the ChatGPT desktop app on my PC connecting to it over SSH. I also tried continuing the work from my smartphone and finding practical ways to review Markdown and HTML files created on the server.
KUSANAGI makes it easy to prepare a web environment, while the underlying Linux server can run a wide range of development tools. By combining the two, the environment used to run websites can also serve as a base for AI-assisted development.
Moving the Development Environment to the KUSANAGI Server
In this setup, the source code, Python virtual environments, and Git working state all reside on the KUSANAGI server. The PC acts as the interface, while file operations and commands are executed on the server.
I separated the storage locations by purpose as follows:
/home/kusanagi/
├── sandbox/work/YYYY-MM-DD_HHMM/ One-off research, experiments, and drafts
├── projects/<project>/ Development projects under ongoing management
└── <profile>/DocumentRoot/ Files served or executed on the webI use sandbox/work for small investigations and experiments, projects for code that I will continue to maintain, and the DocumentRoot of a KUSANAGI profile for anything that needs to be viewed from the web. This article itself was written in a timestamped directory under sandbox/work.
Storing something under /home/kusanagi does not make it safe by itself. I keep repositories under development outside the DocumentRoot, configure Linux permissions and the AI agent’s writable scope, and keep secrets out of the repository. In other words, I combine several boundaries rather than relying on a single measure.
I feel that keeping only the files that truly need to be web-accessible in the DocumentRoot is especially important when developing on a public server.
From Handoff Files to tmux and resume
When working with AI, the conversation that led to the finished files can be just as important as the files themselves.
At first, I summarized the work completed, decisions made, and next steps in a Markdown handoff file. This approach is still valuable because it works even when switching AI tools. At the same time, it requires me to summarize the key points each time, and it is difficult to preserve the finer details of a conversation.
I then started using tmux, which keeps a terminal session running on the server even if the SSH connection drops, as well as codex resume, which reopens a previous conversation. These tools made it easier to reconnect to the same KUSANAGI server and return to work in progress.
There were still a few steps involved when switching PCs: connect to the terminal, find the appropriate session, and resume it. I also needed another way to review changes or respond to questions from the AI on my smartphone.
Handoff files preserve the important points that should remain available across tools. tmux and codex resume make it possible to resume work on the server. Both are useful, but connecting through the desktop app lets me handle conversations, changes, and command output in one place, much as I would when working on a project stored directly on my PC.
Connecting over SSH from the Desktop App
The ChatGPT desktop app can connect to a project on an SSH host. From my PC, I can review the chat and file changes while reading and writing files and running commands on the KUSANAGI server.
After adding the destination to the SSH configuration on the PC, I can select the server and working directory from the app.
Host dev-server
HostName server.example.com
User kusanagi
IdentityFile ~/.ssh/id_ed25519Once I tried it, the division of roles felt more natural than I expected: the PC provides the interface, and the KUSANAGI server provides the actual working environment. I found it particularly convenient to open a chat in the app and continue where I left off, rather than restart the CLI and select the conversation again.
Because the development environment resides on the server, the source code and dependencies remain unchanged when I switch PCs. As long as I can connect over SSH, I can resume work in the same environment.
I also discovered another major difference. With a CLI, showing the AI the state of a screen or an error message requires me to describe it in text or tell the AI where an image file is stored. In the desktop app, I can simply copy and paste a screenshot into the chat.
Being able to show the screen and say, “This is the part that looks wrong,” saves explanation and reduces misunderstandings. For development involving websites and administration screens, this was a much bigger benefit than I had expected.
Sharing Settings Between Codex and Claude Code
In addition to Codex CLI, this KUSANAGI server has Claude Code installed and available through the claude command. I can choose an AI tool based on the task, but inconsistent instructions and operating rules between tools can also lead to inconsistent decisions within the same project.
To address this, I manage the shared configuration in a Git repository named ~/dotfiles. Dotfiles are configuration files used by shells and development tools. In this environment, the global instructions read by Codex and Claude Code are symbolic links to files in the dotfiles repository.
~/.codex/AGENTS.md → ~/dotfiles/agents/AGENTS.md
~/.claude/CLAUDE.md → ~/dotfiles/claude/CLAUDE.mdThe CLAUDE.md file for Claude Code also imports the same AGENTS.md used by Codex.
For example, the tools share rules about keeping Git repositories outside the DocumentRoot on a public server, checking for remote updates at the beginning of a work session, and deciding where handoff files should be stored.
Managing these dotfiles with Git allows me to reuse the same policies on another PC or server. I do not need to explain everything again each time I switch AI tools. Conversations are continued through sessions and handoff files, while the common rules for working are kept consistent through dotfiles.
I keep authentication data, AI session history, SSH keys, and API keys out of the dotfiles repository. Only rules and reusable technical knowledge are shared.
Reviewing Markdown Directly in the App
One feature I found especially useful was Markdown rendering.
When I opened a Markdown file created by Codex on the KUSANAGI server in the ChatGPT desktop app, headings, lists, and other elements appeared in a formatted, readable form. I did not have to reconnect to the server with another editor or download the file to my PC just to review the draft.
This article is also written in Markdown. I ask Codex to revise it, read the result in the same app, and then provide additional instructions for anything I want to change.
This workflow is useful for more than source code. Research notes, specifications, handoff documents, and article drafts can all remain on the server while still being easy to read from the PC. I feel this approach could extend well beyond development work.
Continuing from a Smartphone After Leaving the PC
After setting up ChatGPT Remote, I can connect from the ChatGPT app on my smartphone to the work running on my PC.
ChatGPT app on a smartphone
↓ Remote
ChatGPT desktop app on a PC
↓ SSH
KUSANAGI serverFrom the smartphone, I can send additional instructions, answer questions from Codex, and approve commands. I can also review changes and test results.
I no longer have to remain in front of the PC until a long-running task finishes. Being able to provide a necessary decision while away from my desk is a significant advantage.
The smartphone connects to the PC through Remote, and the PC then connects to the KUSANAGI server over SSH. This means the PC must remain powered on and online, with the ChatGPT desktop app running.
Can HTML Be Opened Directly?
After seeing Markdown rendered in the app, I wondered whether HTML could be viewed in the same way. I created a small sample site with CSS and JavaScript and tried it.
I could inspect the HTML source code, but it did not render as a web page. The “Open with” action also did not work in this SSH-connected environment.
The app can format Markdown as a document. HTML, on the other hand, needs to load CSS and run JavaScript, so it requires a URL that a browser can access. Even though both are text files, they need different ways of being reviewed.
Confirming this difference through an actual test was another useful discovery.
Using a KUSANAGI Profile for Web-Based Review
When I want to review HTML or WordPress in a browser, I can use a KUSANAGI profile.
In KUSANAGI, a profile is a site managed by FQDN on the virtual machine. Running kusanagi provision creates the web server configuration, DocumentRoot, and other required settings. It can provision WordPress as well as a LAMP or LEMP environment without WordPress.
I can use a WordPress profile when reviewing a WordPress theme or plugin, and a LAMP or LEMP profile when reviewing a web application.
After asking AI to write code, being able to continue through testing it in an actual web environment on the same KUSANAGI server is a meaningful advantage of this setup.
Repositories under development and design documents remain in projects, while only the files that need to be viewed from the web are placed on the profile side.
Reviewing Temporary HTML Through an SSH Tunnel
For generated reports, screen mockups, and other HTML files that only need to be viewed temporarily, there is also a way to review them without creating a KUSANAGI profile.
In an actual project, I started Python’s simple HTTP server on the KUSANAGI server. To prevent direct access from the internet, it listens only on 127.0.0.1, which represents the server itself.
A simple HTTP server may sound as though it requires some preparation, but I only need to tell the AI which directory I want to display. It can quickly assemble and run the required command, and I can also ask it to stop the server when I am finished. This made temporary HTML review feel almost effortless.
# On the KUSANAGI server
cd /home/kusanagi/projects/<project>/output
python -m http.server 8000 --bind 127.0.0.1On the PC, I use SSH port forwarding:
# On the PC
ssh -L 8000:127.0.0.1:8000 dev-serverI then open http://localhost:8000/ in the PC’s browser. Port 8000 remains closed to the internet, while the SSH connection lets me view the page locally on my own PC.
The distinction is straightforward: use a KUSANAGI profile for ongoing web review, a simple HTTP server and SSH tunnel for temporary HTML, and Markdown for documents and written materials.
Using Python in the Same Environment
In this KUSANAGI environment, I create a virtual environment for each project based on Python 3.12. I use Python for tasks such as web research and report generation, then ask Codex to maintain and improve the code.
This use of Python comes from treating KUSANAGI as a Linux server. I can use Python and other tools as needed, then turn to a KUSANAGI profile when something needs to be reviewed on the web. I believe the value lies in being able to handle both in the same environment.
Making KUSANAGI the Base for AI-Assisted Development
Since adopting this setup, I feel that my development process has become faster.
The development environment is centralized on the KUSANAGI server and can be operated from the PC. Conversations with AI can continue in the app. When something needs to be shown visually, I can paste a screenshot directly into the chat. Codex and Claude Code can follow the same rules through dotfiles. Markdown documents are easy to review within the app. After leaving the PC, I can continue from my smartphone. When web-based review is needed, I can use a KUSANAGI profile.
Each difference may seem small on its own, but together they reduce the time spent rebuilding environments, re-explaining the context of a conversation, and describing a screen in words. I believe these accumulated improvements are what make the overall development process faster.
By viewing KUSANAGI not only as a platform for running a CMS but also as a Linux environment for AI-assisted development, its range of uses can expand even further.
I would like to continue experimenting with what KUSANAGI and AI can accomplish together and share what I learn.
