diff --git a/xo-pysimulator/.github/workflows/main.yml b/xo-pysimulator/.github/workflows/main.yml
new file mode 100644
index 00000000..621046c5
--- /dev/null
+++ b/xo-pysimulator/.github/workflows/main.yml
@@ -0,0 +1,620 @@
+name: build xo-pyreflect + dependencies
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+env:
+  # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
+  BUILD_TYPE: Release
+
+jobs:
+  build:
+    # The CMake configure and build commands are platform agnostic and should work equally well on Windows or Mac.
+    # You can convert this to a matrix build if you need cross-platform coverage.
+    # See: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: checkout source
+      uses: actions/checkout@v3
+
+    - name: Install dependencies
+      run: |
+        echo "::group::install catch2"
+        # install catch2.  see
+        #   [[https://stackoverflow.com/questions/57982945/how-to-apt-get-install-in-a-github-actions-workflow]]
+        sudo apt-get install -y catch2
+        echo "::endgroup"
+
+        echo "::group::install pybind11"
+        sudo apt-get install -y pybind11-dev
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-cmake
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-cmake
+        path: repo/xo-cmake
+
+    - name: build xo-cmake
+      run: |
+        XONAME=xo-cmake
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}}
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-indentlog
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/indentlog
+        path: repo/xo-indentlog
+
+    - name: build xo-indentlog
+      run: |
+        XONAME=xo-indentlog
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-refcnt
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/refcnt
+        path: repo/xo-refcnt
+
+    - name: build xo-refcnt
+      run: |
+        XONAME=xo-refcnt
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-subsys
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/subsys
+        path: repo/xo-subsys
+
+    - name: build xo-subsys
+      run: |
+        XONAME=xo-subsys
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-reflect
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/reflect
+        path: repo/xo-reflect
+
+    - name: build xo-reflect
+      run: |
+        XONAME=xo-reflect
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-callback
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-callback
+        path: repo/xo-callback
+
+    - name: build xo-callback
+      run: |
+        XONAME=xo-callback
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-printjson
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-printjson
+        path: repo/xo-printjson
+
+    - name: build xo-printjson
+      run: |
+        XONAME=xo-printjson
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-randomgen
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/randomgen
+        path: repo/xo-randomgen
+
+    - name: build xo-randomgen
+      run: |
+        XONAME=xo-randomgen
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-ordinaltree
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-ordinaltree
+        path: repo/xo-ordinaltree
+
+    - name: build xo-ordinaltree
+      run: |
+        XONAME=xo-ordinaltree
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-webutil
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-webutil
+        path: repo/xo-webutil
+
+    - name: build xo-webutil
+      run: |
+        XONAME=xo-webutil
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-reactor
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-reactor
+        path: repo/xo-reactor
+
+    - name: build xo-reactor
+      run: |
+        XONAME=xo-reactor
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-simulator
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-simulator
+        path: repo/xo-simulator
+
+    - name: build xo-simulator
+      run: |
+        XONAME=xo-simulator
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-pyutil
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-pyutil
+        path: repo/xo-pyutil
+
+    - name: build xo-pyutil
+      run: |
+        XONAME=xo-pyutil
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-pyreflect
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-pyreflect
+        path: repo/xo-pyreflect
+
+    - name: build xo-pyreflect
+      run: |
+        XONAME=xo-pyreflect
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-pyprintjson
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-pyprintjson
+        path: repo/xo-pyprintjson
+
+    - name: build xo-pyprintjson
+      run: |
+        XONAME=xo-pyprintjson
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: clone xo-pyreactor
+      uses: actions/checkout@v3
+      with:
+        repository: Rconybea/xo-pyreactor
+        path: repo/xo-pyreactor
+
+    - name: build xo-pyreactor
+      run: |
+        XONAME=xo-pyreactor
+        XOSRC=repo/${XONAME}
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_INSTALL_PREFIX=${PREFIX} ${XOSRC}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}} -j
+        echo "::endgroup"
+
+        echo "::group::local install ${XONAME}"
+        cmake --install ${BUILDDIR}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+    # ----------------------------------------------------------------
+
+    - name: Configure self (pysimulator)
+      # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
+      # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
+      run: |
+        XONAME=xo-pysimulator
+        BUILDDIR=${{github.workspace}}/build_${XONAME}
+        PREFIX=${{github.workspace}}/local
+
+        echo "::group::repo dir tree"
+        tree -L 2 repo
+        echo "::endgroup"
+
+        echo "::group::configure ${XONAME}"
+        cmake -B ${BUILDDIR} -DCMAKE_MODULE_PATH=${PREFIX}/share/cmake -DCMAKE_PREFIX_PATH=${PREFIX} -DCMAKE_INSTALL_PREFIX=${PREFIX} -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
+        echo "::endgroup"
+
+        echo "::group::compile ${XONAME}"
+        cmake --build ${BUILDDIR} --config ${{env.BUILD_TYPE}}
+        echo "::endgroup"
+
+        echo "::group::local dir tree"
+        tree -L 3 ${PREFIX}
+        echo "::endgroup"
+
+        # Execute tests defined by the CMake configuration.
+        # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
+        (cd ${BUILDDIR} && ctest -C ${{env.BUILD_TYPE}})
diff --git a/xo-pysimulator/.gitignore b/xo-pysimulator/.gitignore
new file mode 100644
index 00000000..53a9c92f
--- /dev/null
+++ b/xo-pysimulator/.gitignore
@@ -0,0 +1,6 @@
+# lsp keeps state here
+.cache
+# typical build directory
+.build*
+# lsp: symlink to file in build directory (established manually)
+compile_commands.json
diff --git a/xo-pysimulator/CMakeLists.txt b/xo-pysimulator/CMakeLists.txt
new file mode 100644
index 00000000..03088e39
--- /dev/null
+++ b/xo-pysimulator/CMakeLists.txt
@@ -0,0 +1,27 @@
+# xo-pysimulator/CMakeLists.txt
+
+cmake_minimum_required(VERSION 3.10)
+
+project(xo_pysimulator VERSION 0.1)
+
+include(GNUInstallDirs)
+include(cmake/xo-bootstrap-macros.cmake)
+
+xo_cxx_toplevel_options3()
+
+# ----------------------------------------------------------------
+# c++ settings (usually temporary)
+
+set(PROJECT_CXX_FLAGS "")
+add_definitions(${PROJECT_CXX_FLAGS})
+
+# ----------------------------------------------------------------
+# sources
+
+add_subdirectory(src/pysimulator)
+#add_subdirectory(utest)
+
+# ----------------------------------------------------------------
+# provide find_package() support
+
+xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
diff --git a/xo-pysimulator/README.md b/xo-pysimulator/README.md
new file mode 100644
index 00000000..676fe720
--- /dev/null
+++ b/xo-pysimulator/README.md
@@ -0,0 +1,70 @@
+# python bindings for c++ reflection library (xo-pysimulator)
+
+## Getting Started
+
+### build + install dependencies
+
+- [github/Rconybea/xo-simulator](https://github.com/Rconybea/xo-simulator)
+- [github/Rconybea/xo-pyutil](https://github.com/Rconybea/xo-pyutil)
+- [github/Rconybea/xo-pyreflect](https://github.com/Rconybea/xo-pyreflect)
+- [github/Rconybea/xo-pyprintjson](https://github.com/Rconybea/xo-pyprintjson)
+- [github/Rconybea/xo-pyreactor](https://github.com/Rconybea/xo-pyreactor)
+
+### build + install
+```
+$ cd xo-pysimulator
+$ mkdir build
+$ cd build
+$ INSTALL_PREFIX=/usr/local  # or wherever you prefer, e.g. ~/local
+$ cmake \
+    -DCMAKE_MODULE_PATH=${INSTALL_PREFIX}/share/cmake \
+    -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} \
+    -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} ..
+$ make
+$ make install
+```
+(also see .github/workflows/main.yml)
+
+## Examples
+
+Assumes `xo-pysimulator` installed to `~/local2/lib`
+```
+PYTHONPATH=~/local2/lib:$PYTHONPATH python
+>>> import xo_pysimulator
+>>> dir(xo_pysimulator)
+['Simulator', 'SourceTimestamp', 'TimeSlip', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'make_simulator']
+>>>
+
+## Development
+
+### build for unit test coverage
+```
+$ cd xo-pysimulator
+$ mkdir build-ccov
+$ cd build-ccov
+$ cmake \
+    -DCMAKE_MODULE_PATH=${INSTALL_PREFIX}/share/cmake \
+    -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} \
+    -DCODE_COVERAGE=ON \
+    -DCMAKE_BUILD_TYPE=Debug ..
+```
+
+### LSP (language server) support
+
+LSP looks for compile commands in the root of the source tree;
+while `cmake` creates them in the root of its build directory.
+
+```
+$ cd xo-pysimulator
+$ ln -s build/compile_commands.json  # supply compile commands to LSP
+```
+
+## Examples
+
+Assumes `xo-pysimulator` installed to `~/local2/lib`
+
+```
+PYTHONPATH=~/local2/lib python
+>>> import pysimulator
+>>> dir(pysimulator)
+```
diff --git a/xo-pysimulator/cmake/xo-bootstrap-macros.cmake b/xo-pysimulator/cmake/xo-bootstrap-macros.cmake
new file mode 100644
index 00000000..aba31169
--- /dev/null
+++ b/xo-pysimulator/cmake/xo-bootstrap-macros.cmake
@@ -0,0 +1,35 @@
+# ----------------------------------------------------------------
+# for example:
+#   $ PREFIX=/usr/local   # for example
+#   $ cmake -DCMAKE_MODULE_PATH=prefix -DCMAKE_INSTALL_PREFIX=$PREFIX -B .build
+#
+# will get
+#   CMAKE_MODULE_PATH
+# from xo-cmake-config --cmake-module-path
+#
+# and expect .cmake macros in
+#   CMAKE_MODULE_PATH/xo_macros/xo_cxx.cmake
+# ----------------------------------------------------------------
+
+find_program(XO_CMAKE_CONFIG_EXECUTABLE NAMES xo-cmake-config REQUIRED)
+
+if ("${XO_CMAKE_CONFIG_EXECUTABLE}" STREQUAL "XO_CMAKE_CONFIG_EXECUTABLE-NOT_FOUND")
+    message(FATAL "could not find xo-cmake-config executable")
+endif()
+
+message(STATUS "XO_CMAKE_CONFIG_EXECUTABLE=${XO_CMAKE_CONFIG_EXECUTABLE}")
+
+if (NOT XO_SUBMODULE_BUILD)
+    if (("${CMAKE_MODULE_PATH}" STREQUAL "") OR ("${CMAKE_MODULE_PATH}" STREQUAL prefix))
+        # default to typical install location for xo-project-macros
+        execute_process(COMMAND ${XO_CMAKE_CONFIG_EXECUTABLE} --cmake-module-path OUTPUT_VARIABLE CMAKE_MODULE_PATH)
+        message(STATUS "CMAKE_MODULE_PATH=${CMAKE_MODULE_PATH}")
+    endif()
+endif()
+
+# needs to have been installed somewhere on CMAKE_MODULE_PATH,
+# (e.g. from xo-cmake with the same value for CMAKE_INSTALL_PREFIX)
+#
+include(xo_macros/xo_cxx)
+
+xo_cxx_bootstrap_message()
diff --git a/xo-pysimulator/cmake/xo_pysimulatorConfig.cmake.in b/xo-pysimulator/cmake/xo_pysimulatorConfig.cmake.in
new file mode 100644
index 00000000..9c15f36a
--- /dev/null
+++ b/xo-pysimulator/cmake/xo_pysimulatorConfig.cmake.in
@@ -0,0 +1,4 @@
+@PACKAGE_INIT@
+
+include("${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@Targets.cmake")
+check_required_components("@PROJECT_NAME@")
diff --git a/xo-pysimulator/include/README.md b/xo-pysimulator/include/README.md
new file mode 100644
index 00000000..12c02f54
--- /dev/null
+++ b/xo-pysimulator/include/README.md
@@ -0,0 +1,2 @@
+placeholder for future pysimulator #include files
+
diff --git a/xo-pysimulator/src/pysimulator/CMakeLists.txt b/xo-pysimulator/src/pysimulator/CMakeLists.txt
new file mode 100644
index 00000000..08616537
--- /dev/null
+++ b/xo-pysimulator/src/pysimulator/CMakeLists.txt
@@ -0,0 +1,9 @@
+# xo_pysimulator/src/pysimulator/CMakeLists.txt
+
+set(SELF_LIB xo_pysimulator)
+set(SELF_SRCS pysimulator.cpp)
+
+xo_pybind11_library(${SELF_LIB} ${PROJECT_NAME}Targets ${SELF_SRCS})
+xo_pybind11_header_dependency(${SELF_LIB} xo_pyreactor)
+xo_pybind11_dependency(${SELF_LIB} simulator)
+xo_pybind11_header_dependency(${SELF_LIB} xo_pyutil)
diff --git a/xo-pysimulator/src/pysimulator/pysimulator.cpp b/xo-pysimulator/src/pysimulator/pysimulator.cpp
new file mode 100644
index 00000000..c1077b0a
--- /dev/null
+++ b/xo-pysimulator/src/pysimulator/pysimulator.cpp
@@ -0,0 +1,66 @@
+/* @file pysimulator.cpp */
+
+#include "pysimulator.hpp"
+#include "xo/pyreactor/pyreactor.hpp"
+
+#include "xo/simulator/Simulator.hpp"
+#include "xo/simulator/SourceTimestamp.hpp"
+#include "xo/simulator/TimeSlip.hpp"
+#include "xo/pyutil/pyutil.hpp"
+//#include <pybind11/pybind11.h>
+//#include <pybind11/stl.h>
+//#include <pybind11/chrono.h>
+
+namespace xo {
+    using xo::reactor::Reactor;
+    //using xo::scope;
+    namespace py = pybind11;
+
+    namespace sim {
+        PYBIND11_MODULE(PYSIMULATOR_MODULE_NAME(), m) {
+            /* e.g. for Reactor */
+            PYREACTOR_IMPORT_MODULE(); //py::module_::import("pyreactor")
+
+            /* module docstring */
+            m.doc() = "pybind11 plugin for xo.simulator";
+
+            m.def("make_simulator",
+                  []() {
+                      return xo::sim::Simulator::make(xo::time::timeutil::epoch());
+                  },
+                  "create new Simulator instance");
+
+            py::class_<TimeSlip>(m, "TimeSlip")
+                .def_property_readonly("sim_tm", &TimeSlip::sim_tm)
+                .def_property_readonly("real_tm", &TimeSlip::real_tm)
+                // .def("__repr__", &TimeSlip::display_string)  // TODO
+                ;
+
+            py::class_<Simulator,
+                       Reactor,
+                       xo::ref::intrusive_ptr<Simulator>>(m, "Simulator")
+                .def_static("make", []() { return xo::sim::Simulator::make(xo::time::timeutil::epoch()); })
+                .def_property_readonly("start_tm", &Simulator::t0)
+                .def_property_readonly("last_tm", &Simulator::last_tm)
+                .def_property_readonly("n_event", &Simulator::n_event)
+                .def_property_readonly("is_exhausted", &Simulator::is_exhausted)
+                .def("next_tm", &Simulator::next_tm)
+                .def("next_src", &Simulator::next_src)
+                .def("timeslip", &Simulator::timeslip)
+                .def("throttled_event_dt", &Simulator::throttled_event_dt)
+                .def("heap_contents", &Simulator::heap_contents)
+                .def("log_heap_contents",
+                     [](Simulator & self) {
+                         scope log(XO_LITERAL(log_level::always, "pysimulator", ".log_heap_contents"));
+                         self.log_heap_contents(&log);
+                     })
+                .def("__repr__", &Simulator::display_string);
+
+            py::class_<SourceTimestamp>(m, "SourceTimestamp")
+                .def("__repr__", &SourceTimestamp::display_string);
+
+        } /*pysimulator*/
+    } /*namespace sim*/
+} /*namespace xo*/
+
+/* end pysimulator.cpp */
diff --git a/xo-pysimulator/src/pysimulator/pysimulator.hpp.in b/xo-pysimulator/src/pysimulator/pysimulator.hpp.in
new file mode 100644
index 00000000..db3656c5
--- /dev/null
+++ b/xo-pysimulator/src/pysimulator/pysimulator.hpp.in
@@ -0,0 +1,25 @@
+/* @file pysimulator.hpp
+ *
+ * automatically generated from src/xo_pysimulator/pysimulator.hpp.in
+ * see src/xo_pysimulator/CMakeLists.txt
+ */
+
+/* python requires module name = library name
+ * example:
+ *   PYBIND11_MODULE(PYSIMULATOR_MODULE_NAME(), m) { ... }
+ */
+#define PYSIMULATOR_MODULE_NAME() @SELF_LIB@
+
+/* example:
+ *   py::module_::import(PYSIMULATOR_MODULE_NAME_STR)
+ */
+#define PYSIMULATOR_MODULE_NAME_STR "@SELF_LIB@"
+
+/* example:
+ *   PYSIMULATOR_IMPORT_MODULE()
+ * replaces
+ *   py::module_::import("pysimulator")
+ */
+#define PYSIMULATOR_IMPORT_MODULE() py::module_::import("@SELF_LIB@")
+
+/* end pysimulator.hpp */