DEV Community: Jan De Dobbeleer

Oh My Posh ❤️ Claude Code

Jan De Dobbeleer — Sun, 28 Dec 2025 14:28:00 +0000

Terminal customization just got a lot smarter. Oh My Posh now integrates with Claude Code through its statusline functionality, bringing real-time AI session information and development context directly into your Claude Code prompt.

This isn't just another segment: it's a bridge between your development workflow and AI-powered coding assistance.

What is Claude Code's `statusline`?

Claude Code's statusline feature allows you to create custom status displays that appear at the bottom of the Claude Code interface, similar to how terminal prompts work in shells. The statusline receives rich JSON data about your current AI session via stdin, including:

Model information: Which Claude model you're using (Claude Sonnet, Claude Opus, etc.)
Token usage: Input/output tokens, context window utilization, and usage percentages
Cost tracking: Real-time cost calculations and session duration
Workspace context: Current and project directories
Session metadata: Unique session IDs and version information

The statusline updates automatically when conversation messages change (throttled to every 300ms max), and Oh My posh creates the status display with full ANSI color support.

Setting Up the Integration

Configuration is straightforward. Add this to your Claude Code settings:

{
  "statusLine": {
    "type": "command",
    "command": "oh-my-posh claude",
    "padding": 0
  }
}

That's it! Oh My Posh will automatically detect when Claude Code provides session data and display the relevant information in your prompt.

It's important to note that the claude CLI command operates differently from your regular prompt configuration. When used as a statusline command, Oh My Posh runs in a special mode that's completely separate from your standard terminal prompt. This means you'll likely want to create a dedicated, minimal configuration specifically for Claude Code that focuses on displaying AI session information rather than your usual prompt elements.

Custom configuration

By default, the oh-my-posh claude command provides a built-in statusline that shows your current working directory, git context, active model name, and context window usage as a visual gauge. To customize this display, use the --config flag to specify your own theme configuration file that includes a custom claude segment tailored to your preferences.

{
  "statusLine": {
    "type": "command",
    "command": "oh-my-posh claude --config ~/.claude.omp.json",
    "padding": 0
  }
}

Just make sure the configuration also leverages the data available in the claude segment to visualize the stats you care about. As this isn't like a regular prompt integration, keep the statusline a single line and use left and right aligned prompt blocks to play with.

{
  "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
  "palette": {
    "black": "#262B44",
    "blue": "#4B95E9",
    "green": "#59C9A5",
    "orange": "#F07623",
    "red": "#D81E5B",
    "sapling": "#a6d189",
    "white": "#E0DEF4",
    "yellow": "#F3AE35"
  },
  "accent_color": "32",
  "blocks": [
    {
      "type": "prompt",
      "alignment": "left",
      "segments": [
        {
          "options": {
            "dir_length": 3,
            "folder_separator_icon": "\ue0bb",
            "style": "fish"
          },
          "template": "{{ if .Segments.Git.Dir }} \uf1d2 <i><b>{{ .Segments.Git.RepoName }}{{ if .Segments.Git.IsWorkTree }} \ue21c{{ end }}</b></i>{{ $rel :=  .Segments.Git.RelativeDir }}{{ if $rel }} \ueaf7 {{ .Format $rel }}{{ end }}{{ else }} \uea83 {{ path .Path .Location }}{{ end }} ",
          "foreground": "p:white",
          "leading_diamond": "\ue0b6",
          "background": "p:orange",
          "type": "path",
          "style": "diamond"
        },
        {
          "options": {
            "branch_icon": "\ue0a0",
            "fetch_status": true
          },
          "template": " {{ if .UpstreamURL }}{{ url .UpstreamIcon .UpstreamURL }} {{ end }}{{ .HEAD }}{{if .BranchStatus }} {{ .BranchStatus }}{{ end }}{{ if .Working.Changed }} \uf044 {{ nospace .Working.String }}{{ end }}{{ if .Staging.Changed }} \uf046 {{ .Staging.String }}{{ end }} ",
          "foreground": "p:black",
          "leading_diamond": "<parentBackground,background>\ue0b0</>",
          "trailing_diamond": "\ue0b4",
          "background": "p:green",
          "type": "git",
          "style": "diamond",
          "foreground_templates": [
            "{{ if or (.Working.Changed) (.Staging.Changed) }}p:black{{ end }}",
            "{{ if or (gt .Ahead 0) (gt .Behind 0) }}p:white{{ end }}"
          ],
          "background_templates": [
            "{{ if or (.Working.Changed) (.Staging.Changed) }}p:yellow{{ end }}",
            "{{ if and (gt .Ahead 0) (gt .Behind 0) }}p:red{{ end }}",
            "{{ if gt .Ahead 0 }}#49416D{{ end }}",
            "{{ if gt .Behind 0 }}#7A306C{{ end }}"
          ]
        }
      ]
    },
    {
      "type": "prompt",
      "alignment": "right",
      "segments": [
        {
          "leading_diamond": "\ue0b6",
          "template": " \udb82\udfc9 {{ .Model.DisplayName }} \uf2d0 {{ .TokenUsagePercent.Gauge }} ",
          "foreground": "p:white",
          "background": "accent",
          "type": "claude",
          "style": "diamond"
        },
        {
          "options": {
            "charged_icon": "\ue22f ",
            "charging_icon": "\ue234 ",
            "discharging_icon": "\ue231 "
          },
          "cache": {
            "duration": "10m",
            "strategy": "session"
          },
          "leading_diamond": "<background,parentBackground>\ue0b2</>",
          "trailing_diamond": "\ue0b4",
          "template": "{{ if not .Error }} {{ .Icon }}{{ .Percentage }}%{{ end }}",
          "foreground": "#111111",
          "background": "accent",
          "type": "battery",
          "style": "diamond",
          "background_templates": [
            "{{if eq \"Discharging\" .State.String}}p:orange{{end}}",
            "{{if eq \"Full\" .State.String}}p:green{{end}}"
          ]
        }
      ]
    }
  ],
  "version": 4
}

The Claude Code segment

Oh My Posh's new claude segment taps into this statusline data to bring AI session awareness directly into your terminal prompt. When you use the oh-my-posh claude command as your statusline command in Claude Code, you get access to a wealth of session information that can be displayed in your prompt without needing to know the technical details.

Example Configuration

Here's a sample configuration that shows the model name and context usage:

{
  "type": "claude",
  "style": "diamond",
  "leading_diamond": "\ue0b6",
  "trailing_diamond": "\ue0b4",
  "foreground": "#FFFFFF",
  "background": "#FF6B35",
  "template": " \udb82\udfc9 {{ .Model.DisplayName }} \uf2d0 {{ .TokenUsagePercent.Gauge }} "
}

This displays something like: 🤖 Claude 4.5 Sonnet ▰▰▰▱▱

The gauge provides instant visual feedback on how much of your context window you've consumed, which is crucial for managing long coding sessions.

The Technical Details

Under the hood, Oh My Posh reads the rich JSON session data that Claude Code provides via stdin when used as a statusline command. The segment only activates when Claude Code session data is available, so there's no performance impact when you're not using Claude Code.

Getting Started

If you're already using Oh My Posh, adding Claude Code integration is as simple as:

Install Claude Code if you haven't already
Add the statusline configuration to your Claude Code settings
Optionally create your own configuration including the claude segment
Start a Claude Code session and watch your prompt come alive

For detailed configuration options and all available properties, check out the complete Claude segment documentation.

What's Next?

This integration opens up exciting possibilities. Imagine prompts that:

Change color based on token usage percentage
Show different icons for different AI models
Display cost warnings when sessions get expensive
Integrate with any other segment to show additional development context

The foundation is there, and now it's up to the community to build amazing configurations that make AI-powered development even more seamless.

Going beyond autocomplete with AI Agents

Jan De Dobbeleer — Tue, 09 Dec 2025 09:18:04 +0000

Over the past year, I’ve seen many software engineers and teams dive into AI adoption, only to face disappointment when the hype delivers little more than autocomplete tricks or basic unit test generation. The outputs often ignore standards, architecture, and conventions, creating more work instead of reducing it. Rather than abandoning this inevitable shift, we should learn from those who succeed.

What’s missing for those who struggle with AI adoption? It’s the ability to guide the model with context. Many tools allow you to automatically inject tailored instructions for each task, shaping the output for success. In this post, I’ll demonstrate how to do this with GitHub Copilot and Claude Code, setting you on the path to becoming an AI-native software engineer.

Why instructions change everything

They make implicit team rules explicit and version-controlled.
They steer the agent’s defaults: style, architecture, naming, testing, commit conventions, security guardrails.
They raise consistency across the team and reduce review friction.
They open the door towards more AI automation.

When instructions live in-repo, the agent reads them like any engineer would—then generates code that fits your standards by default.

Instruction file types: tool-specific vs. universal

Different AI tools support different instruction file conventions, but the underlying principles remain the same: provide context, enforce standards, and guide behaviour.

GitHub Copilot uses .github/copilot-instructions.md for repository-wide instructions that apply to all requests. For more granular control, you can create path-specific instructions using .github/instructions/*.instructions.md files with frontmatter scoping. These files can target specific paths, languages, or audiences (IDE vs. CLI), making them highly flexible for monorepos and polyglot projects.

Claude Code looks for CLAUDE.md in your project root. This single file contains all Claude-specific instructions, though you can organize complex guidance using markdown sections and headers.

Universal approach: Many teams adopt AGENTS.md as a tool-agnostic convention. Place an AGENTS.md file at the root or nested in directories, and any agent tool can consume it. This works well when you use multiple AI tools or want a single source of truth that isn't vendor-locked.

The choice depends on your team's needs:

Use .github/copilot-instructions.md for simple, repository-wide Copilot guidance.
Use .github/instructions/*.instructions.md when you need fine-grained, path-specific control.
Use AGENTS.md for simplicity and portability across different AI tools.

Now let's explore how to architect these instructions for maximum effectiveness.

Architecture: layering context so it stays relevant and cheap

Think of context in layers:

Global repository instructions: High-level standards that apply everywhere (language style, testing baseline, security posture, commit messages, PR checklist).
Local, nested instructions: Directory-scoped AGENTS.md files or GitHub Copilot instruction files that apply to specific domains (e.g., backend/api vs. frontend/ui). These are only loaded when relevant, saving tokens and maintenance.
Task-specific prompt files: Small, reusable prompt templates for common jobs (e.g., "add endpoint", "migrate tests", "write changelog"). They eliminate boilerplate prompting and keep users on the happy path.

The result: less noise, lower cost, more accurate outputs.

In Practice

Imagine a typical full-stack application: a React frontend talking to a Node.js API, each with distinct patterns. The frontend team enforces accessibility standards and component testing. The backend team requires validated payloads, structured error responses, and integration tests. Without instructions, an AI agent might generate a backend endpoint that returns raw errors or a frontend component missing ARIA labels — creating review friction and rework. Instruction files ensure the agent knows these domain-specific rules and conventions upfront.

File structure examples

GitHub Copilot approach with .github/ directory:

repo/
├── .github/
│   ├── copilot-instructions.md    # Repository-wide Copilot instructions
│   ├── instructions/               # Path-specific instruction files with frontmatter scopes
│   │   ├── backend.md
│   │   ├── frontend.md
│   │   └── security.md
│   └── prompts/                    # Task-specific prompt files (optional)
├── backend/
    └── frontend/

Universal AGENTS.md approach (tool-agnostic):

repo/
├── AGENTS.md                       # Repository-wide instructions
├── backend/
│   ├── AGENTS.md                   # Backend-specific instructions
│   └── api/
│       └── AGENTS.md               # API-specific instructions
└── frontend/
    └── AGENTS.md                   # Frontend-specific instructions

Example instruction files

Repository-wide instructions (applies to entire codebase):

# Repository-wide Instructions

## Commits
- Use Conventional Commits (feat:, fix:, docs:, refactor:, test:, chore:)
- Reference issue numbers in commit body (e.g., "Relates to #123")
- Keep subject line under 72 characters

## Testing
- Require tests for all new features and bug fixes
- Maintain minimum 80% code coverage
- Run full test suite before submitting PR

## Code Review
- Keep PRs focused and under 400 lines when possible
- Self-review checklist: tests pass, no secrets, lint clean
- Tag at least one reviewer familiar with the domain

## Security
- Never commit secrets, API keys, or credentials
- Use environment variables for configuration
- Run security scanners in CI pipeline
- Validate and sanitize all external inputs

## Documentation
- Update README when adding new features or changing setup
- Document complex algorithms inline
- Keep API documentation in sync with code changes

## Writing Style
- Always wrap filenames in backticks (e.g., `config.json`, `AGENTS.md`, `.github/copilot-instructions.md`)
- Use clear, descriptive variable and function names
- Write comments for non-obvious logic, not for self-explanatory code

Backend-specific instructions:

---
name: Backend
scope:
  paths: ["backend/**"]
  languages: ["js", "ts"]
  audience: ["ide", "cli"]
---
# Backend API Standards

## Goals
- Add/modify API endpoints with proper validation, telemetry, and tests.

## Code style
- Follow repo ESLint/Prettier. Prefer functional handlers; avoid singletons.

## HTTP/Errors
- Use RFC7807 problem+json. Map domain errors to 4xx with stable codes.

## Testing
- For each handler, add integration tests hitting the router; seed minimal fixtures.

Frontend-specific instructions:

---
name: Frontend
scope:
  paths: ["frontend/**"]
  languages: ["ts", "tsx"]
  audience: ["ide", "cli"]
---
# Frontend Engineering Standards
- Use React + Vite; prefer function components and hooks.
- Enforce a11y: labels, roles, keyboard navigation.
- Co-locate component tests next to components with *.spec.tsx.

Key takeaways

Keep each instruction file concise; multiple files may apply simultaneously.
Scope narrowly by paths/languages to avoid conflicts and reduce tokens.
Instruction merging behavior: Both GitHub Copilot and AGENTS.md approaches merge path-specific/scoped instructions with repository-wide files. All applicable instruction files are combined and sent to the model together, enabling layered context that becomes more specific as you navigate deeper into the codebase.
Frontmatter scoping (shown above) is specific to GitHub Copilot's .github/instructions/ files.
AGENTS.md files use directory proximity for scoping instead of frontmatter.
Both approaches achieve the same goal: context layering that keeps instructions relevant and maintainable.

Task automation: prompt files and sub-agents

Beyond static instructions, both GitHub Copilot and Claude Code support structured, reusable task templates that guide common workflows. These eliminate repetitive prompting and ensure consistent outputs across your team.

Prompt files (GitHub Copilot) are parameterized markdown templates stored in a prompts/ directory. They define inputs, steps, and constraints for recurring tasks like add API endpoint or migrate tests. Users invoke them from the IDE or CLI, supply the parameters, and get guided, standardized results.

Sub-agents (Claude Code) work similarly but can be more dynamic. Each sub-agent focuses on a specific responsibility (e.g., Security Review, API Synthesizer) with its own instruction set. Claude can either route to the appropriate sub-agent automatically based on your task and the sub-agent's description, or you can invoke a specific sub-agent explicitly by name in your prompts.

Both approaches serve the same purpose: turning common tasks into repeatable, version-controlled workflows.

Prompt files (GitHub Copilot)

Create a prompts/ directory (see VS Code Copilot Prompt Files) with reusable task prompts.

Prompt files can be stored in two locations:

Workspace-level: .github/prompts/ (available in current workspace only)
User-level: VS Code profile folder (available across all workspaces, syncable via Settings Sync)

prompts/
├── add-endpoint.md
├── migrate-tests.md
└── write-changelog.md

Example prompt file with frontmatter:

---
description: Create an API endpoint with validation, tests, and docs
mode: agent
tools: ['githubRepo', 'search/codebase']
model: Claude Sonnet 4
---

Use the repository's Backend instructions.
Add ${input:method} ${input:route} with validation and router-level tests.

Usage: In VS Code, use the / command in chat to invoke prompts:

/add-endpoint method=POST route=/api/users

The prompt file parameters are filled automatically, and Copilot generates code following the template's instructions.

Sub-agents (Claude Code)

See Claude Code: Sub-agents for detailed configuration. Each sub-agent can have its own focused instruction set and optional scope restrictions.

Just like prompt files, sub-agents can be stored in two locations:

Project-level: .claude/agents/ (available in current project only)
User-level: ~/.claude/agents/ (available across all projects)

Example sub-agent configuration:

---
name: add-endpoint
description: Create API endpoints with validation, tests, and documentation. Use proactively after modifying backend code.
tools: Read, Edit, Bash, Grep, Glob
model: inherit
---

Use the repository's Backend instructions.
Add endpoints with validation and router-level tests.

Usage: Invoke sub-agents explicitly by mentioning them with @:

@add-endpoint Create a POST /api/users endpoint

Or let Claude route automatically by describing the task without specifying a sub-agent. Claude will select the appropriate sub-agent based on context and task requirements.

Instruction writing and refinement

Start with generic, widely available best-practice instructions

Use markdown header for emphasis and agent guidance.
Keep instructions concise and to the point.
Goal: Establish a baseline and understand prompting techniques.

TIP Get inspiration from the awesome-copilot repository.

Meta Prompting → Model driven refinement

Use your AI tool to generate/refine instructions based on your repository's context.
Ask the model to remove ambiguity and keep instructions concise.
Goal: Generate prompts that are understandable by the AI agent.
Example: Generate me Copilot instructions for my blog post content based on the style you find in the current posts inside /content/post*.md. Validate for ambiguity and keep the instructions concise.

TIP Use Visual Studio Code's built-in Generate Workspace Instructions File to get an out of the box prompt that generates the instructions file based on your repository's context.

Meta + Feedback → Self-analysis & future adjustment

After generating output, ask the model to explain deviations from guidelines and adjust its approach for future tasks by modifying the instructions.
Goal: Build a feedback loop for continuous improvement.
Example: Go through our conversation and iterations we made and implement/adjust instructions to avoid these mistakes in the future.

Making agentic AI work for you

The difference between autocomplete on steroids and genuinely transformative AI assistance isn't the model — it's the context you provide. Teams who succeed with AI agents don't just adopt the tools; they codify their implicit knowledge into explicit, version-controlled instructions. They start by inventorying their domain rules and standards, then layer them strategically: repository-wide baselines, domain-specific guidance, and task-focused prompts. They keep these instructions close to the code, maintain them like any other asset, and refine them through feedback loops.

This isn't optional groundwork for some future state of AI development. It's the necessary first step that transforms AI from a novelty into a reliable engineering partner. Without it, you're asking agents to guess your standards. With it, you're building a foundation for automation that scales across your team and compounds over time.

References and further reading

References:

Do tattoos influence the probability of getting hired?

Jan De Dobbeleer — Sat, 09 Jun 2018 05:20:38 +0000

Saw this one on Twitter and immediately thought of sharing it here because I'm really curious about the responses.

Does having tattoos influence the probability of being hired as a developer/programmer?

My status: I have a full sleeve on my right arm and one other visible tattoo on my left arm. So far, I haven't had any negative experiences with recruiting within IT, but that might be directly related to the type of companies and cultures I'm engaging with.

If you have tattoos, what are your experiences? Or maybe you don't but know about a policy at work? Or, maybe, just maybe, you've got an opinion about this topic? Share away!

A viable alternative to Operator Mono in Visual Studio Code

Jan De Dobbeleer — Fri, 01 Jun 2018 18:35:25 +0000

After seeing Night Owl, a color theme for VSCode created by Sarah Drasner leveraging the use of italics and a font supporting this, I was hesitant about either pruchasing Dank Mono (less mature, but already super nice Operator Mono alternative), or start the search for free alternative. Given that it's in my nature to switch interests every two seconds, I made the call not to spend money on a hype, but instead look for hacks which must surely be out there.

At first, my search for free alternatives to Operator Mono guided me towards FiraCodeiScript made by Ken Krocken. What it does is make two fonts look like one, so you have Fira Code as the regular font and Script12 as the italic font. They were edited using FontForge, a tool used to create or alter fonts. My first impression was That's pretty cool, but after a while I couldn't help but not really liking Script12.

I figured I had to create my own version. As I'm a programmer, I didn't want to mess with a GUI tool and decided to go for a Python script using FontTools to edit the font files and make them appear as one font family. The information on how to do this is available in the following issue on the Open Soure Idea's repository on GitHub.

FontTools turned out to work against rather than with me, for some reason I couldn't always figure out where to find the fields I needed to adjust. The quest for a better module began. My terminal fonts always come from the Nerd Fonts repository, and as they also need to rename fonts due to licensing issues, it was the best place to start digging.

They use a Python script to edit the font files and append loads of cool stuff, and guess what, it's using the Python module included in FontForge. Cool! Easy, right? Nope. I'm using Windows 10 by choice and this time, it hit me in the nuts. You can't install the module using pip install FontForge, it's included in the installation of FontForge. On Linux you can install bindings to expose the module and use it in your scripts, but there's no such option for Windows.

Back to the thinking cabin! Looking at how FontForge works, it embeds Python 2.7 (🤦‍) which gives you the FontForge module out of the box. Being pragmatic and all, I decided to use that Python executable to create the script. Using VSCode, you can adjust your debug settings (located at projectroot\.vscode\launch.json) to do just that.

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Experimental: Current File (Integrated Terminal)",
            "type": "pythonExperimental",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "pythonPath": "C:\\Program Files (x86)\\FontForgeBuilds\\bin\\ffpython.exe"
        }
    ]
}

This way you can easily import the FontForge module and create a script that alterts two font files to a newly invented font family. I really like Fira Code, so I downloaded Fura Code from Nerd Fonts to hold all interesting bits and pieces, and fell in love with Yellowtail to use as the italic variant.

import fontforge
import uuid


def change_font_data_and_save(font_location, familyname,
                              sub_family, output_dir, uid):
    source_font = fontforge.open(font_location)
    source_font.familyname = familyname
    source_font.fullname = '{} {}'.format(familyname, sub_family)
    source_font.fontname = '{}-{}'.format(familyname, sub_family)
    source_font.appendSFNTName(str('English (US)'), str('Family'),
                               source_font.familyname)
    source_font.appendSFNTName(str('English (US)'), str('SubFamily'),
                               sub_family)
    source_font.appendSFNTName(str('English (US)'), str('UniqueID'),
                               uid)
    source_font.appendSFNTName(str('English (US)'), str('Preferred Family'),
                               source_font.familyname)
    source_font.appendSFNTName(str('English (US)'), str('Compatible Full'),
                               source_font.fullname)
    source_font.generate(output_dir + '/' + source_font.fullname + '.ttf',
                         flags=(str('opentype'), str('PfEd-comments')))


regular_font = 'path_to_fura_code.tff'
italic_font = 'path_to_yellowtail.ttf'
output_dir = './output'
familyname = 'VSCode Font'
uid = str(uuid.uuid4())
change_font_data_and_save(regular_font, familyname, 'Regular', output_dir, uid)
change_font_data_and_save(italic_font, familyname, 'Italic', output_dir, uid)

This works like a charm, you get two fonts in the output folder which you can then install as one font family, adjust VSCode to use that font and profit. With one annoying side-effect. Depending on the difference between the two fonts, you might need to scale one of them. I did so for Yellowtail resulting in some letters being chopped off when a sentence start with an italic word. In the sample above, whenever def was on position 0 of a line, the d is slightly cut off at the beginning. I don't need to explain this is not a desired effect.

I went to have a look at the other custom fonts and they all have the same issue depending on the font they use. An alternative solution which works a lot better is to use the Custom CSS and JS plugin to alter the font size when a word is italic (can be distinguished by the mkti class). But, and this is important, if we do this, then we lose the use-case for a custom font.

So, after losing a few hours to get this right, I went for the custom CSS solution. I installed all variants of Fura Code and the Yellowtail font and created an override for the mkti class using the Custom CSS and JS plugin. To do so, create a file with the following content. Alter the font family per your liking, after playing with a few handwritten fonts, I went for Flottflott in the end.

.mtki {
    font-size: 1.6em;
    font-family: Flottflott;
}

This will make the text bigger, but still respect the bounds of the window. So you get the same result font wise, but better. If you're on Windows, make sure to run VSCode elevated when applying the style (and re-applying whenever you update VSCode).

On to theming. We all use different themes, and not every theme has support for italic keywords. Now, instead of creating a custom theme, I want to teach you how to override the theme settings so that they will be applied no matter the theme you're using. I switch themes like clothes (you can define whether that applies a lot or not 😲), so I don't want to go fiddling with this every time.

As it turns out, VSCode adheres to the TextMate grammer syntax to define how it needs to render code. I found a nice guide from another undisclosed editor, which, in combination with looking at existing themes and how they do it, allowed me to get started. Currently my config looks like this.

"editor.fontFamily": "FuraCode NF",
"editor.fontLigatures": true,
"vscode_custom_css.imports": [
    "file://C:/Users/jan/.vscode_css_settings.css"
],
"vscode_custom_css.policy": true,
"editor.tokenColorCustomizations": {
    "textMateRules": [
        {
            "scope": [
                "storage.modifier",
                "variable.language",
                "markup.italic",
                "punctuation.definition.keyword",
                "keyword.control.import",
                "storage.type.class",
                "storage.type.function",
                "storage.modifier"
            ],
            "settings": {
                "fontStyle": "italic"
            }
        },
        {
            "scope": [
                //following will be excluded from italics
                "comment",
                "invalid",
                "keyword.operator",
                "keyword.control.conditional",
                "storage.type.function.arrow.js"
            ],
            "settings": {
                "fontStyle": ""
            }
        }
    ]
},

There are two overrides, one that explicitly says what to render italic (and thus add the mkti class), and another to exclude keywords from being rendered italic. This way I can use whatever theme I like, my settings will make the right words appear italic and pretty. This list isn't complete, there are a lot more which can be added. In the end it depends on the theme, language and personal taste to define what it needs to look like.

I hope you'll have as much fun customizing your editor as I had trying to find a silver bullet 😄.

Originally posted at: https://blog.itdepends.be/operator-mono-alternative/

Dotnet Core served with a slice of Cake

Jan De Dobbeleer — Tue, 29 May 2018 07:12:01 +0000

While preparing slides for an introduction into DevOps I was about to give to a bunch of knowledge eager .NET developers, I was looking to build a sample project to illustrate a nice setup to start with. DotNet Core was a given, with it's great CLI interface and ability to run everywhere, the choice was obvious. But when it came to build tools, I felt that the ones I knew (psake, fake), could easily startle people new to this whole build .NET code outside of Visual Studio kind of thing. There was one kid on the block which had been on my list to look at for quite a while, and you know how much I love sidetracking and spending way too much time exploring exciting new stuff!

Long story short, I fell in love with Cake. Compared to other build automation tools, it comes with a lot of nice first- and third-party integrations, reducing the need for boilerplate code. Before, I made use of heavily customized PowerShell scripts for versioning and uploading of artifacts and test results, Cake comes with all of that out of the box. Another advantage, if the feature you're looking isn't available, it's easily extensible. All the wins \0/.

So, what would my ideal setup look like? Well, we need a few things when it comes to a nice CI setup. First, I want all the build logic to be managed from the source code, no dependencies in the GUI as it easily becomes a burden to maintain and switch context. On the plus side, we want to be able to run it locally as well as on our build agent, and Cake will help us achieve exactly that. Secondly, here's a list of stuff I'm looking for that Cake should handle for me:

Split the build logic in tasks
Group tasks to allow different types of builds
Provide standard build functionality (clean, restore, build)
Restore NuGet packages
Enable static code analysis and linting
Run unit tests and upload coverage

Let's have a look at each of those.

Split the build logic in tasks

To get started with Cake, you can make use of the bootstrappers. There are two versions, one for Windows, and one for Unix systems. I added both in my sample project, just make sure to use the correct line endings on each platform, or go for LF everywhere (yeah, I said it). If you're using Visual Studio Code, feel free to have a look at the Cake extension, Gary Ewan Park even made accompanying videos to explain its capabilities.

After installing a bootstrapper, make sure to pin the Cake version. You can do so by adding a file at tools/packages.config with the following content.

<?xml version="1.0" encoding="utf-8"?>
<packages>
    <package id="Cake" version="0.27.2" />
</packages>

With all this in place we have the following files, other than the project files:

.
build.ps1
build.sh
tools
- packages.config

Remember, we've got a DotNet Core project set up, in case you don't have one, feel free to clone the sample project to follow along. The purpose of the bootstrapper files build.ps1 and build.sh is to be able to resolve all dependencies, including Cake, and not having to worry about any of that. You can have a look at the source to see what they do, but the file we're really interested in is build.cake.

Create the build.cake file which will contain al our build logic from now on. The Cake website provides a nice getting started sample, so let's build from there.

var target = Argument("target", "Default");

Task("Default")
  .Does(() =>
{
  Information("Hello World!");
});

RunTarget(target);

You can see we've met the first requirement. We have the ability to define tasks that can contain whatever logic we need. Written entirely in C#, this is a huge advantage and reduces the startup cost as a .NET developer. The task called Default is the one that runs when no parameters are defined. You can immediately see what it does by using the bootstrapper in your CLI tool of choice: ./build.ps1 (but seriously, use ConEmu). The output looks like this:

Preparing to run build script...
Running build script...

========================================
Default
========================================
Hello World!

Task                          Duration
--------------------------------------------------
Default                       00:00:00.0136945
--------------------------------------------------
Total:                        00:00:00.0136945

Group tasks to allow different types of builds

Using Cake, it's easy to group a few tasks as one. Let's say we want to split our Hello world task into two meaningful ones and assign the combination as the Default.
We can define separate tasks and have Default depend on both of them.

var target = Argument("target", "Default");

Task("Hello")
  .Does(() =>
{
  Information("Hello");
});

Task("World")
  .Does(() =>
{
  Information("World");
});

Task("Default")
  .IsDependentOn("Hello")
  .IsDependentOn("World");

RunTarget(target);

When you run this using ./build.ps1, you can see both tasks being executed. Now that we understand the basics, it's time to implement the actual logic for our DotNet Core app.

Provide standard build functionality (clean, restore, build)

Cake provides support for DotNet Core via a built-in third party plugin. To clean a project, you can make use of DotNetCoreClean, but in my case, as I'm used to cleaning up after myself, I used a custom implementation in the sample project. The main reason is that there's a lot more output coming from a build than the output from MSBuild, and I want to make sure everything is nice and tidy. In case you'd opt for the built-in, the task would look something like this.

Task("Clean")
  .Does(() =>
{
  DotNetCoreClean("./src/project");
});

Remember, you can do anything you want here, so maybe you're fine with this, or prefer a more custom approach, the choice is yours.

The approach to restore nuget packages and build the projects is almost identical other than having the ability to define a few settings. You can find all information on the Cake website, or have a peek at the sample project for inspiration.

Enable static code analysis and linting

Now that we have our base setup ready, we finally get to the interesting bits. When we think about .NET and code analysis, I hope you can't help but think about Resharper. By coincidence, JetBrains provides two CLI tools , inspectCode and dupFinder. The first one handles all checks included in Resharper, the second one will look for duplicate code blocks. The cool thing is that we can make it validate the same ruleset we enforce via Visual Studio, by saving them to your project's DotSettings file. You can read more about that here, we'll be using the 'Solution team-shared' layer in this sample.

What might also be good to know is that Resharper in Visual Studio provides support for .editorconfig files, but those can't be used in combination with the CLI version. I spent about an hour trying to get it to work to finally come to that conclusion with the help of Maarten Balliauw.

To use these tools in our Cake script, we need a few dependencies. First of all, and maybe that's not at all a problem in your case, we need the Visual Studio build tools and enable DotNet Core suppport. As a developer who only uses Visual Studio Code, I did not have these preinstalled, causing a lot of pain and unclear errors. So, if you're like me, install these on your host or build machine if that's not already the case. Secondly we can make use of a Cake plugin called, you guessed it, Resharper. To include it, add the following line on top of your build.cake script. This will make the bootstrapper resolve the dependency when running Cake.

#tool "nuget:https://www.nuget.org/api/v2?package=JetBrains.ReSharper.CommandLineTools&version=2018.1.0"

Make sure to lock the version number of external dependencies to avoid unwanted side effects. Updates to these tools should always be validated beforehand.

All that's left is to create tasks to validate our code.

Task("DupFinder")
    .Description("Find duplicates in the code")
    .Does(() =>
{
    var settings = new DupFinderSettings() {
        ShowStats = true,
        ShowText = true,
        OutputFile = $"{artifactsDir}/dupfinder.xml",
        ExcludeCodeRegionsByNameSubstring = new string [] { "DupFinder Exclusion" },
        ThrowExceptionOnFindingDuplicates = true
    };
    DupFinder("./App.sln", settings);
});

Task("InspectCode")
    .Description("Inspect the code using Resharper's rule set")
    .Does(() =>
{
    var settings = new InspectCodeSettings() {
        SolutionWideAnalysis = true,
        OutputFile = $"{artifactsDir}/inspectcode.xml",
        ThrowExceptionOnFindingViolations = true
    };
    InspectCode("./App.sln", settings);
});

It will use our DotSettings file out of the box, so no need to specify it. You can look at the sample to see the syntax, if you need to know where to find the names for these rules, have a look at the documentation.

We can add another interesting tool caled DependenciesAnalyser. It will look at your nuget dependencies and see if they are outdated. It won't fail the build but it's such a good thing to include as you might otherwise forget about this (I know I do). When I run it at the time of writing, it provides the following ouput, telling me I can update two dependencies.

EDIT: It seems this makes the UNIX builds fail. I created an issue on the project to remind myself to have a look. For the time being I removed the task from the sample.

========================================
Analyse-Dependencies
========================================
Executing task: Analyse-Dependencies
Resolving assembly Domain.XmlSerializers, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null
---------------------------------
Project: ./App\App.csproj
---------------------------------

---------------------------------
Project: ./Test\Test.csproj
coverlet.msbuild is on version 2.0.0. The dependency is outdated.
FluentAssertions is on version 5.3.0. The dependency is up-to-date.
Microsoft.NET.Test.Sdk is on version 15.7.2. The dependency is outdated.
xunit is on version 2.3.1. The dependency is up-to-date.
xunit.runner.visualstudio is on version 2.3.1. The dependency is up-to-date.
---------------------------------

Finished executing task: Analyse-Dependencies

For convenience we can group these as one Task, to facilitate running the checks separately when needed.

Task("Validate")
    .Description("Validate code quality using Resharper CLI. tools.")
    .IsDependentOn("Analyse-Dependencies")
    .IsDependentOn("DupFinder")
    .IsDependentOn("InspectCode");

Run unit tests and upload coverage

Writing unit tests has always been a pleasure on DotNet. My base setup consists of a few winners (opinion, it's my blog after all) like xUnit and Fluent Assertions. Creating a test project can be done using the dotnet new xunit command, and installing packages follows the dotnet add package FluentAssertions syntax. You can run the tests using dotnet test. A sample setup and explanation can be found on Microsoft's website if you need a more in-depth introduction.

Cake provides the same ease of use compared to the other standard DotNet Core functionality, which makes our task look like this.

Task("Test")
    .Description("Run all unit tests within the project.")
    .Does(() =>
{
    DotNetCoreTest("./Test/Test.csproj");
});

Now, this gives us the ability to run unit tests, but how about calculating code coverage? It turns out there's an MSBuild extension that enables just that. It's called coverlet and you can add it as a nuget package to your test project: dotnet add package coverlet.msbuild. To use its functionality, we need to add a few additional parameters to the Test task.

var settings = new DotNetCoreTestSettings
     {
         ArgumentCustomization = args => args.Append("/p:CollectCoverage=true")
                                             .Append("/p:CoverletOutputFormat=opencover")
                                             .Append("/p:ThresholdType=line")
                                             .Append($"/p:Threshold={coverageThreshold}")
     };
DotNetCoreTest("./Test/Test.csproj", settings);

What it does is add those parameters to MSBuild, which will then use coverlet to calculate the coverage. We want to have line coverage, which we can specify using /p:ThresholdType=line. This will calculate the percentage depending on whether or not every relevant line is covered by a unit test. If the percentage drops below a certain threshold (defined op top of build.cake), it will fail the build. The output format is opencover which we need to export the result to Coveralls.io, where we can keep track of our coverage cross build and cross branch. The advantage of using an external service is that you can't simply adjust the threshold to fix a build failure. It will also hold you back to merge changes to master in case of a drop in coverage (thresholds can be agile about this) when configured that way in GitHub for example.

To upload the changes to Coveralls.io we need three extra dependencies.

#tool "nuget:https://www.nuget.org/api/v2?package=coveralls.io&version=1.4.2"
#addin "nuget:https://www.nuget.org/api/v2?package=Cake.Coveralls&version=0.8.0"
#addin "nuget:https://www.nuget.org/api/v2?package=Cake.Incubator&version=2.0.1"

Incubator is needed to work with environment variables as we don't want to include our Coveralls.io API token in the build script (seriously, don't). No matter the CI tool, you can always add environment variables to use in your build logic. The proper way is to have them in the build script as encrypted variables, so that they can't be used other than during the CI phases, but you can still adjust them via source control. I'm using Appveyor myself and it can encrypt variables to add to your appveyor.yml script.

To upload the coverage statistics via Cake, we make use of the Coveralls add-on. Combine this with incubator to retrieve the API token during build and we can upload the file generated by coverlet.

Task("Upload-Coverage")
    .Does(() =>
{
    var isRunningOnAppveyor = EnvironmentVariable<bool>("APPVEYOR", false);
    if (!isRunningOnAppveyor)
        return;
    Information("Running on Appveyor, uploading coverage information to coveralls.io");
    CoverallsIo("./Test/coverage.xml", new CoverallsIoSettings()
    {
        RepoToken = EnvironmentVariable("coveralls_token")
    });
});

Now that we've got all of this available, we can define a basic CI task to execute on the build machine.

Task("CI")
    .Description("Build the code, test and validate")
    .IsDependentOn("Build")
    .IsDependentOn("Test")
    .IsDependentOn("Validate")
    .IsDependentOn("Upload-Coverage");

As we're entering a world where C# has the ability to run on other machines than Windows alone, I made a Unix specific build task too.

Task("CI-UNIX")
    .Description("Build the code, test and validate")
    .IsDependentOn("Build")
    .IsDependentOn("Test");

This way we have Appveyor to run the tests on Windows (including the static analysis and code coverage uploading) and Linux, and Travis.ci to run the tests on OSX. As we've got a Cake build script, all we need is the two config files to tell our CI instances what to do. Beware, Appveyor can run PowerShell on Windows and Linux, so we need to check where we are before executing the same command twice.

image:
- Visual Studio 2017
- Ubuntu
environment:
  coveralls_token:
    secure: HMJLoYbkSD1p35JnHiBjv02frHKMvasoD9J6wLnzjSUsdPwFwiHU8t0SwcvyAYi1
build_script:
  - pwsh: |
      if ($isWindows) {
        .\build.ps1 -Target CI
      }
  - sh: ./build.sh --target=CI-UNIX

language: csharp
mono: latest
dotnet: 2.1.200
os: osx
script:
  - ./build.sh --target=CI-UNIX

If you're curious about the output or build time, you can have a look at the project on Appveyor's or Travis' website.

This is as far as I wanted to go with this. I'll try to keep the project up-to-date with interesting add-ons, or maybe you know of some improvement and would like to propose a PR? Do not hesitate to get in touch!

Source Code

Originally posted at: https://blog.itdepends.be/dotnet-core-cake/

Intercept HTTP traffic exiting a docker container

Jan De Dobbeleer — Thu, 29 Mar 2018 20:27:16 +0000

Imagine the following problem. You are working on an application running inside a docker container and you feel the need to inspect the http requests being executed by your application. Coming from an app development background myself, it can be a huge benefit to use proxy tooling like mitmproxy to see the actual request being made instead of staying stuck trying to figure out what's wrong. Or, use the proxy to alter requests and easily test use cases or reproduce bug reports. All in all, there's a significant gain in lead time when using the right tool for the job. Otherwise we'd still be adding print statements everywhere just for the sake of debugging (I know you're doing it).

In this case, I have a Python Django web app running in a Debian Jessie container and I needed to see the flow of requests being made towards the backend REST API. Installing mitmproxy is a breeze, as it's a cross platform tool, you can follow the installation guide for your platform. I'm running it using the WSL on Windows myself (Ubuntu). Before doing anything else, start mitmproxy and get comfortable. The default port for capturing traffic is 8080, change it using the -p <portnumber> option in case conflicts would occur.

$ mitmproxy

Docker provides proxy support out of the box which is convenient.
As we've got mitmproxy running on our host machine, we want to route all traffic exiting the container to that once. To do so, I created a new docker-compose.override file which holds all settings and (almost all) logic.

version: '2'
services:
  mv-web:
    environment:
      - HTTP_PROXY=mitmproxy:8080
      - HTTPS_PROXY=mitmproxy:8080
    extra_hosts:
      - "mitmproxy:10.125.2.187"
    command: sh -c 'python3 certificate.py && python3 manage.py runserver 0.0.0.0:8020'

In the above example I only added the settings relevant to illustrate the solution. You can see two environment variables, HTTP_PROXY and HTTPS_PROXY. These tell the container to route all exiting traffic towards mitmproxy, who's added as an extra host. The ip address 10.125.2.187 is the one of my host machine, change it to whatever yours is.

Now, you might notice there's another little item in there called python3 certificate.py which runs just before we start the Django app. If you'd only use the proxy settings, http requests would enter mitmproxy just fine, but https requests will not show up. The reason is that mitmproxy uses it's own certificate to be able to decrypt the traffic flowing through. As a result, the requests will get blocked as the OS doesn't trust that certificate (like it should).

Initially I tried to add the certificate to the container's OS trusted certificate store, but that didn't work out as planned. I could run a curl command inside the container to an https endpoint and it flowed through mitmproxy like a boss, but when I started the Django app, https requests kept being aborted. It took me a while to figure out what was going on. Our Django app uses the Requests library to execute http calls. This one in turn uses certifi to create its trusted certificate store, which didn't have a copy of mitmproxy's root certificate causing all https calls being silenced and not exiting the container.

The solution, once you know it, is straightforward. Add a script called certificate.py to your container (either by volume mapping, or as a build step) together with mitmproxy's root certificate (located at ~/.mitmproxy/mitmproxy-ca-cert.pem) and edit the docker-compose.override.yml file to execute certificate.py before starting the Django app.

Copy mitmproxy's root certificate to your Django app's root folder:

$ cp ~/.mitmproxy/mitmproxy-ca-cert.pem <project root>

Create a new file called certificate.py in the same project root:

import certifi

caroot = certifi.where()
with open('mitmproxy-ca-cert.pem', 'rb') as mitm:
    cert = mitm.read()
with open(caroot, 'ab') as out:
    out.write(cert)
print('w00t, added mitmproxy root cert to certifi!')

Now, when you up the docker container with compose, you'll see all traffic flowing through mitmproxy! Happy debugging!

Small additions

Multiple docker-compose files

When using a docker-compose.override.yml file and you've already specified another non-standard docker-compose file, make sure to use -f twice to load both (or more) settings files. So, imagine your settings file is called docker-compose.standalone.yml and you've added all files following this tutorial, the command to up your container becomes:

docker-compose -f .\docker-compose.standalone.yml -f .\docker-compose.override.yml up

Our override file should be last so that no setting can be overwritten by settings in previous files, The last in wins.

Check firewall settings

As I'm running this on Windows, I still had to open up port 8080 to allow the container to connect to mitmproxy. Double check on whatever system you're using that this isn't the thing causing a headache before proceeding 😑.

But I'm not using Python or Requests

In case you want to do this but don't have a Python app using Requests, you can try to add the certificate to the container's OS as I mentioned before. For some reason, I also had to set it on every container start, but that's not too much hassle. Instead of certificate.py, create a file called certificate.sh with the following content:

mkdir /usr/local/share/ca-certificates/extra
cp mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/extra/root.cert.crt
update-ca-certificates

Then, change the docker-compose.override.yml file to execute this one instead of certificate.py:

command: sh -c './certificate.sh && <whatever the command>'

The example assumes a Debian based container, make sure to alter certificate.sh to add the root certificate to the correct location according to your container's OS.

Have fun!

Hi, I'm Jan De Dobbeleer

Jan De Dobbeleer — Sat, 01 Apr 2017 12:41:39 +0000

I have been coding for 4 years.

You can find me on Twitter as @Jan_Joris

I live in Diest, Belgium.

I work for Unleashed

I mostly program in these languages: PowerShell, Python, C#, Ruby, Java, Javascript.

I am currently learning more about everything.

Nice to meet you.